Environment Doctor

nat doctor runs a suite of pre-flight checks to validate your environment and surface any configuration issues before you start scanning.

Run nat doctor any time you're troubleshooting unexpected behavior. It gives you a quick, structured summary of what's working and what isn't.

Usage

⚠️

If nat doctor isn't recognized as a command, you're running a version older than v1.4.0 where this command was introduced. Run pip install --force-reinstall --no-cache-dir nat-engine to update, then try again.

nat doctor [flags]

Flag	Description
`--json`	Output check results as a JSON array for CI/automation
`--verbose`	Show detailed diagnostics and fix hints for each check

Exit codes: 0 = all checks passed, 1 = one or more failures.

The 8 checks

Each check reports one of four states:

State	Meaning
✅ PASS	Check succeeded
❌ FAIL	Check failed — action required
⚠️ WARN	Check passed with caveats — review recommended
⏭️ SKIP	Check was not applicable in your configuration

Check overview

#	Check	Description
1	Python version	Verifies Python ≥ 3.10 is installed
2	Required pip extras	Checks that `pyyaml`, `alembic`, `httpx`, and `uvicorn` are importable
3	Critical environment variables	Checks `DATABASE_URL` (self-hosted/default mode) and `NAT_API_KEY` (saas/default mode); skipped if mode is `cli`
4	`.natrc` configuration	Loads and validates the `.natrc` YAML config file from the current directory or home directory
5	Database connectivity	Runs `SELECT 1` via SQLAlchemy against `DATABASE_URL`; skipped if `DATABASE_URL` is not set
6	Alembic migration state	Compares the current DB revision against the Alembic head; warns if pending migrations exist
7	LLM provider keys	Checks for `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`; skipped if neither is set
8	Exporter connectivity	If `.natrc` has an `export.type`, calls `test_connection()` on that exporter

Example output

Normal output

$ nat doctor

NAT Environment Doctor
──────────────────────────────────────────────────────
✅ PASS  Python version          Python 3.11.6 (≥ 3.10 required)
✅ PASS  Required pip extras     pyyaml, alembic, httpx, uvicorn — all present
✅ PASS  Environment variables   DATABASE_URL ✓  NAT_API_KEY ✓
✅ PASS  .natrc config           Loaded from ~/.natrc (mode: saas)
✅ PASS  Database connectivity   Connected to PostgreSQL in 14 ms
⚠️ WARN  Alembic migrations      1 pending migration (run: nat upgrade --migrate)
✅ PASS  LLM provider keys       OPENAI_API_KEY ✓
✅ PASS  Exporter connectivity   GitHub Issues — connection OK

7 passed, 1 warning, 0 failures

Verbose output

$ nat doctor --verbose

NAT Environment Doctor
──────────────────────────────────────────────────────
✅ PASS  Python version
        Found: Python 3.11.6
        Required: ≥ 3.10

✅ PASS  Required pip extras
        pyyaml 6.0.1   ✓
        alembic 1.13.1 ✓
        httpx 0.27.0   ✓
        uvicorn 0.29.0 ✓

✅ PASS  Environment variables
        DATABASE_URL  → postgresql://user:***@localhost/nat ✓
        NAT_API_KEY   → nat_pk_*** ✓

✅ PASS  .natrc config
        Path: /home/user/.natrc
        Mode: saas
        Export type: github_issues

✅ PASS  Database connectivity
        Driver: asyncpg  |  Round-trip: 14 ms

⚠️ WARN  Alembic migrations
        Current revision: abc123
        Head revision:    def456
        Pending: 1 migration
        Fix: run `nat upgrade --migrate` to apply pending migrations

✅ PASS  LLM provider keys
        OPENAI_API_KEY ✓

✅ PASS  Exporter connectivity
        Type: github_issues
        Repo: myorg/myrepo
        Status: connection OK

7 passed, 1 warning, 0 failures

JSON output

Use --json for CI pipelines and automation tooling:

nat doctor --json

[
  {
    "check": "python_version",
    "status": "pass",
    "message": "Python 3.11.6 (≥ 3.10 required)"
  },
  {
    "check": "pip_extras",
    "status": "pass",
    "message": "pyyaml, alembic, httpx, uvicorn — all present"
  },
  {
    "check": "env_vars",
    "status": "pass",
    "message": "DATABASE_URL ✓  NAT_API_KEY ✓"
  },
  {
    "check": "natrc_config",
    "status": "pass",
    "message": "Loaded from ~/.natrc (mode: saas)"
  },
  {
    "check": "database_connectivity",
    "status": "pass",
    "message": "Connected to PostgreSQL in 14 ms"
  },
  {
    "check": "alembic_migrations",
    "status": "warn",
    "message": "1 pending migration — run: nat upgrade --migrate"
  },
  {
    "check": "llm_keys",
    "status": "pass",
    "message": "OPENAI_API_KEY ✓"
  },
  {
    "check": "exporter_connectivity",
    "status": "pass",
    "message": "github_issues — connection OK"
  }
]

CI/CD usage

Run nat doctor as a pre-flight step in your pipeline to catch environment issues before they cause a scan to fail:

# .github/workflows/nat-scan.yml
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install NAT
        run: pip install nat-engine
 
      - name: Validate environment
        run: nat doctor --json
        # Exits with code 1 if any check fails, blocking the pipeline
 
      - name: Run scan
        run: nat scan --url ${{ secrets.STAGING_URL }} --spec ./openapi.yaml

Use nat doctor --json in CI — the structured output can be parsed by notification scripts or stored as a pipeline artifact for audit purposes.

Common failures and fixes

Python version check fails

❌ FAIL  Python version  Python 3.9.7 — upgrade to Python 3.10 or later

Upgrade Python:

# Ubuntu/Debian
sudo apt install python3.11
python3.11 -m pip install nat-engine
 
# macOS
brew install python@3.11

Missing pip extras

❌ FAIL  Required pip extras  Missing: alembic, httpx

Install the missing packages:

pip install alembic httpx

Or reinstall nat-engine with all extras:

pip install --upgrade "nat-engine[all]"

DATABASE_URL not set

❌ FAIL  Environment variables  DATABASE_URL is not set

Set the variable in your shell or .env file:

export DATABASE_URL="postgresql://user:password@localhost:5432/nat"

See .env.example (opens in a new tab) for all supported variables.

Pending Alembic migrations

⚠️ WARN  Alembic migrations  1 pending migration

Apply the migrations:

nat upgrade --migrate

Or manually:

alembic upgrade head

Exporter connectivity fails

❌ FAIL  Exporter connectivity  github_issues — connection error: 401 Unauthorized

Check your exporter credentials in .natrc and verify the API token has the required permissions. See the Exporter Configuration guide for details.

Related guides

Setup Wizard — interactive first-time configuration
CLI Reference — full nat command reference
Troubleshooting — common issues and solutions

Was this helpful?

Upgrade & Uninstall Demo Mode