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.9+
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

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)

Getting more help

• 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