Common Issues

Installation issues

pip install nat-engine fails

Symptom: Error during pip install, such as Could not find a version that satisfies the requirement nat-engine.

Solutions:

1. Check Python version: python --version — requires Python 3.10+
2. Upgrade pip: pip install --upgrade pip
3. Try installing in a fresh virtual environment:

   python3 -m venv .venv && source .venv/bin/activate
   pip install nat-engine

nat: command not found after installation

Symptom: nat command is not found even after a successful pip install.

Solutions:

1. If installed in a virtual environment, activate it first: source .venv/bin/activate
2. Check if the pip scripts directory is in your PATH:

   python3 -m site --user-scripts  # Shows the scripts directory
   Add it to your PATH if missing.
3. Try running via Python module: python3 -m nat --version

nat doesn't recognize setup, upgrade, doctor, or uninstall

Symptom: Running nat upgrade, nat setup, nat doctor, or nat uninstall returns:

nat: error: argument command: invalid choice: 'upgrade'

The nat --help output only lists older commands: scan, security-scan, weights, heal, test-gen, completions, demo.

Why this happens: You are running an older version of nat-engine that was installed before these commands were added in v1.4.0. This commonly occurs when:

1. A stale pip cache served an older wheel during upgrade
2. You have multiple Python environments (system Python vs. virtualenv) and the wrong one is active
3. A cached .pyc bytecode file is being used instead of updated source

Solutions:

1. Check your installed version: nat --version — commands setup, upgrade, doctor, and uninstall require v1.4.0 or later
2. Force a clean reinstall (bypasses pip cache):

   pip install --force-reinstall --no-cache-dir nat-engine
3. If using a virtualenv, make sure it's activated:

   source .venv/bin/activate
   nat --version
4. If developing from the repo source, reinstall in editable mode:

   pip install -e .
5. Verify the fix — nat --help should now list all commands including setup, upgrade, doctor, and uninstall

Scan issues

"0 endpoints discovered"

Symptom: NAT reports discovering 0 endpoints after scanning.

Solutions:

1. Confirm the target URL is reachable: curl -I https://api.example.com
2. If using a spec, verify it's valid and the servers[].url matches your --url
3. Check that authentication isn't required to reach the API's discovery endpoints
4. Try --verbose to see the raw probe requests and responses:

   nat scan --url https://api.example.com --verbose

Scan exits immediately with "Scan error"

Symptom: NAT exits with exit code 2 immediately after starting.

Solutions:

1. Enable verbose logging: nat scan --url ... --verbose
2. Check network connectivity to the target
3. Verify your API key is valid: nat auth status
4. Check for TLS certificate issues: curl -v https://api.example.com

Scan is very slow

Symptom: Scan takes much longer than expected.

Solutions:

1. Reduce timeout if your API is fast: --timeout 10
2. Increase concurrency if your API can handle it: --concurrency 10
3. Use a spec to skip the discovery phase: --spec ./openapi.yaml
4. Exclude known-slow endpoints: --exclude "/api/v1/reports/*"

False positives in report

Symptom: A finding appears in the report but you've confirmed it's not a real vulnerability.

Solution: Dismiss the finding with a reason:

nat findings dismiss --id FINDING_ID --reason false_positive --note "CORS policy is intentional"

Server issues (self-hosted)

Server fails to start

Symptom: nat server start exits immediately.

Solutions:

1. Check if the port is already in use: ss -tlnp | grep 8080
2. Check permissions on the data directory:

   ls -la ~/.nat/data    # Should be writable by the current user
3. Check for missing NAT_SECRET_KEY:

   NAT_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") nat server start

Dashboard is unreachable

Symptom: Browser shows "Connection refused" when accessing the dashboard.

Solutions:

1. Verify the server is running: nat server status
2. Check the bind address — if host is 127.0.0.1, the server is only accessible locally
3. Check firewall rules: sudo ufw status

Report issues

Report is empty / "No findings"

Symptom: Scan completes but the report shows no findings.

This may be expected if your API is well-secured. To confirm NAT tested your API:

1. Open the report and check the Coverage section — were endpoints actually tested?
2. Run with --verbose to confirm requests were sent
3. Ensure you're scanning against a staging environment with actual vulnerabilities (try nat demo first)

API errors

401 Unauthorized

Symptom: Every API call returns 401 Unauthorized.

Solutions:

1. Ensure the X-API-Key header is set (not Authorization: Bearer):

   curl https://api.nat-testing.io/api/v1/usage \
     -H "X-API-Key: $NAT_API_KEY"
2. Confirm your key starts with nat_pk_ — keys in any other format are invalid.
3. Check that the key has not been rotated or revoked in the dashboard under Settings → API Keys.

429 Too Many Requests

Symptom: API calls return 429 Too Many Requests.

Why this happens: You have exceeded your plan's per-minute request rate limit. Check the Retry-After header in the response for the number of seconds to wait.

Rate limits by plan:

Solutions:

1. Add exponential back-off and retry logic that honours the Retry-After header.
2. If you consistently hit the limit, consider upgrading your plan.

402 Payment Required — Quota Exceeded

Symptom: POST /api/v1/scan returns 402 Payment Required with error code QUOTA_EXCEEDED.

Why this happens: You have consumed all functional scans in the current billing period.

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly scan quota exhausted. Quota resets on 2025-02-01.",
  "quota_reset_date": "2025-02-01T00:00:00Z"
}

Solutions:

1. Wait for reset — quota resets automatically on quota_reset_date. Check it via GET /api/v1/usage.
2. Upgrade your plan — log in to the dashboard (opens in a new tab) and go to Settings → Billing.
3. Reduce scan frequency — pause non-critical CI/CD scans until the quota resets.

See Billing Issues for more detail.

Functional testing issues

Scan returns 402 FEATURE_NOT_AVAILABLE for functional tests

Symptom: Starting a scan with "mode": "functional" returns a 402 error with code FEATURE_NOT_AVAILABLE.

Why this happens: Functional testing (visual regression, accessibility, performance) requires a Pro or Team plan.

Solutions:

1. Log in to the dashboard (opens in a new tab) and go to Settings → Billing to upgrade your plan.
2. Alternatively, upgrade via the API:

   curl -X POST https://api.nat-testing.io/api/v1/billing/checkout \
     -H "X-API-Key: $NAT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"plan": "pro", "success_url": "https://app.nat-testing.io/dashboard"}'

Visual regression shows unexpected diffs on first run

Symptom: The first functional scan reports visual diffs even though nothing has changed.

Why this happens: NAT creates a baseline screenshot on the first scan. If no prior baseline exists, the first scan captures the baseline and may flag transient rendering differences.

Solutions:

1. Run the scan a second time — the second run compares against the baseline captured in the first.
2. If the diffs are expected (e.g., after a deliberate UI change), reset the baseline:

   nat scan --url https://app.example.com --mode functional --reset-baseline
   Or via the API by adding "reset_baseline": true to the request body.

Accessibility score is lower than expected

Symptom: The compliance score is below your target even though your app appears accessible.

Solutions:

1. Review the specific violations returned in GET /api/v1/scan/{id}/accessibility — each violation includes the affected element, WCAG rule, and a help_url with remediation guidance.
2. Check the impact level: critical and serious violations have the most effect on the score.
3. Ensure you are testing with authentication if your app requires login to reach most pages — unauthenticated scans will only cover public pages.

Performance score is lower than expected

Symptom: The performance score is significantly below your Lighthouse measurements.

Why this happens: NAT measures performance from a neutral network environment (not from localhost or a fast CI runner). This gives you a real-world perspective but may differ from local Lighthouse results.

Solutions:

1. Focus on the lcp_ms, cls, and tbt_ms fields — these have the largest impact on the score.
2. Use the help_url links in the performance report for specific optimization guidance.
3. Pages with heavy server-side rendering or CDN-dependent assets may score differently between runs. Check TTFB (ttfb_ms) as a first diagnostic step.

Functional test scan takes much longer than a security scan

Symptom: Functional scans take 5–10× longer than security scans on the same target.

Why this happens: Functional testing uses real browser automation (Chromium headless) to load and interact with pages, which is significantly slower than sending API requests.

Solutions:

1. Reduce the number of pages tested by using --exclude to skip non-critical URLs.
2. Lower --concurrency if your staging environment has limited capacity (e.g., --concurrency 2).
3. Run functional tests on a schedule (e.g., nightly) rather than on every pull request.

Getting more help

• Run nat doctor for a quick environment health check — catches most setup issues automatically. See the Environment Doctor guide
• If nat doesn't recognize a command, check that you're running nat-engine v1.4.0+ — see the stale install section above
• Run nat <command> --help for command-specific help
• Use --verbose on any command to enable detailed output
• Check the FAQ for answers to common questions
• See the specific troubleshooting guides:
  • Auth Issues
  • Connection Errors
  • CI/CD Issues
  • Docker Issues