> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt
> Use this file to discover all available pages before exploring further.

# debug

> Validate project configuration and test the warehouse connection.

Checks that your project config is valid, the adapter is resolvable, and the warehouse connection works. Useful for diagnosing setup issues.

## Usage

```bash theme={null}
sqb debug [flags]
```

## What it checks

The command runs three groups of checks:

**Runtime** - SQLBuild version, Python version, Python path, OS info.

**Configuration** - Finds and validates `sqlbuild_project.toml`, loads `sqlbuild_local.toml` if present, resolves the adapter and active target.

**Connection** - Displays connection settings (secrets are masked), attempts to connect to the warehouse, and runs `SELECT 1` to verify query execution.

## Flags

| Flag              | Description                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `--no-connection` | Skip the connection and query tests. Useful for validating config without warehouse access. |
| `--json`          | Output results as JSON instead of formatted text.                                           |

## Example

```bash theme={null}
sqb debug
```

```
SQLBuild Diagnostics

Runtime:
  sqlbuild version: 0.2.1
  python version: 3.14.3
  python path: /home/user/.venv/bin/python3
  os info: Linux-6.6.87

Configuration:
  project file: /home/user/waffle_shop/sqlbuild_project.toml [OK found and valid]
  local config: /home/user/waffle_shop/sqlbuild_local.toml [OK found]
  project: waffle_shop [OK loaded]
  adapter: snowflake [OK found]
  target: dev [OK resolved]

Connection:
  account: FJMQFQV-OJ66172
  authenticator: programmatic_access_token
  database: SQB_DB
  role: role_sqb_test
  schema: TEST
  token: ****
  user: svc_sqb_test
  warehouse: SQB_WH
  connection test: [OK connected]
  query test: [OK SELECT 1]
```

## Exit codes

Returns `0` when all checks pass, `1` when any check fails (e.g. connection refused, invalid config).