Troubleshooting

atlas doctor

Run atlas doctor to check your Atlas configuration and diagnose issues:

bun run atlas -- doctor

This validates:

• Datasource connectivity (can Atlas reach your database?)
• Provider API key (is the LLM provider configured?)
• Semantic layer (do entity YAML files exist?)
• Internal database (can Atlas reach DATABASE_URL?)
• Auth configuration (are required variables set?)
• Sandbox backend (is isolation working?)
• Config file (can atlas.config.ts be loaded?)

Each check reports pass, warn, or fail with actionable guidance.

Startup Errors

Atlas validates its environment on first request and reports structured diagnostic codes.

MISSING_DATASOURCE_URL

No analytics datasource configured.

# Fix: set the datasource URL
ATLAS_DATASOURCE_URL=postgresql://user:pass@host:5432/db

DB_UNREACHABLE

Cannot connect to the analytics datasource. Check:

• Connection string format and credentials
• Network access from Atlas to the database
• SSL configuration (try ?sslmode=require for PostgreSQL, ?ssl=true for MySQL)
• Firewall rules and security groups

MISSING_API_KEY

LLM provider API key not set. Atlas needs one to run the agent.

# Example for Anthropic
ATLAS_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

MISSING_SEMANTIC_LAYER

No semantic/entities/*.yml files found. Generate them:

bun run atlas -- init                    # Profile your database
bun run atlas -- init --demo             # Use demo data instead

INVALID_SCHEMA

The ATLAS_SCHEMA value is not a valid SQL identifier or doesn't exist in the database.

# Check the schema exists
psql "$ATLAS_DATASOURCE_URL" -c "SELECT schema_name FROM information_schema.schemata"

WEAK_AUTH_SECRET

BETTER_AUTH_SECRET is shorter than 32 characters. Generate a strong secret:

openssl rand -base64 48

MISSING_AUTH_ISSUER

BYOT mode requires ATLAS_AUTH_ISSUER when ATLAS_AUTH_JWKS_URL is set.

MISSING_AUTH_PREREQ

Auth mode is set explicitly but required variables are missing. For example, ATLAS_AUTH_MODE=api-key without ATLAS_API_KEY.

ACTIONS_REQUIRE_AUTH

The action framework requires authentication. Set up any auth mode other than none.

INVALID_CONFIG

atlas.config.ts failed to load. Check for syntax errors or missing dependencies.

Connection Issues

PostgreSQL SSL

Most managed Postgres providers require SSL:

# Require SSL (recommended)
ATLAS_DATASOURCE_URL=postgresql://user:pass@host:5432/db?sslmode=require

# Skip certificate verification (development only)
ATLAS_DATASOURCE_URL=postgresql://user:pass@host:5432/db?sslmode=no-verify

MySQL Timeouts

If MySQL connections drop, check:

• wait_timeout on the MySQL server (default 8 hours)
• Connection pool idle timeout (configure via atlas.config.ts)
• Network latency between Atlas and MySQL

Connection Refused

• Verify the host and port are correct
• Check that the database server is running
• Ensure no firewall is blocking the connection
• For Docker: use host.docker.internal instead of localhost to reach the host machine

SQL Validation Errors

"Query rejected: DML/DDL detected"

The SQL contains mutation keywords (INSERT, UPDATE, DELETE, DROP, etc.). Atlas only allows SELECT queries.

"Table not in whitelist"

The query references a table that doesn't have an entity YAML file in semantic/entities/. Either:

• Add the table: bun run atlas -- init --tables <table_name>
• Or set ATLAS_TABLE_WHITELIST=false to disable (not recommended for production)

"Failed to parse SQL"

The SQL couldn't be parsed by node-sql-parser. This typically means:

• Database-specific syntax that the parser doesn't support
• A syntax error in the generated SQL
• Complex CTEs or window functions that the parser mishandles

Check ATLAS_LOG_LEVEL=debug for the full SQL that was rejected.

Sandbox Issues

"nsjail not found"

nsjail is not on PATH and ATLAS_NSJAIL_PATH is not set.

• Docker: Build with the nsjail stage (see examples/docker/Dockerfile)
• Local dev: nsjail is optional -- the just-bash fallback works for development
• Explicit mode: If ATLAS_SANDBOX=nsjail is set, nsjail must be available (hard fail)

"Sidecar unreachable"

When ATLAS_SANDBOX_URL is set, Atlas expects the sidecar service to be running at that URL.

# Check sidecar health
curl http://localhost:8080/health

Verify the sidecar container is running and the URL is correct.

"Permission denied" in nsjail

nsjail requires specific Linux kernel capabilities. Check:

• The container has SYS_ADMIN capability (for mount namespaces)
• User namespaces are enabled in the kernel
• The nsjail binary has correct permissions

Auth Issues

401 Responses

CORS with Managed Auth

Cross-origin managed auth requires both CORS and CSRF configuration:

ATLAS_CORS_ORIGIN=https://app.example.com
BETTER_AUTH_TRUSTED_ORIGINS=https://app.example.com
BETTER_AUTH_URL=https://api.example.com

See Authentication - Cross-origin deployment.

JWKS Fetch Failures (BYOT)

Atlas caches JWKS keys but needs to reach the endpoint on startup. If your JWKS URL is unreachable:

• Check network access from Atlas to the identity provider
• Verify the URL format (must be HTTPS, end in .json or /jwks)
• Check for firewall rules blocking outbound HTTPS

Debug Logging

Enable debug logs to see detailed agent actions, SQL validation steps, and request traces:

ATLAS_LOG_LEVEL=debug

Log levels: trace, debug, info (default), warn, error, fatal.

Key things to look for in debug logs:

• Agent steps -- Tool calls, SQL generated, validation results
• SQL validation -- Which layer rejected a query and why
• Auth decisions -- Mode detection, role extraction, rate limit checks
• Sandbox execution -- Command sent, stdout/stderr, exit code

Getting Help

• GitHub Issues -- Bug reports and feature requests
• Run atlas doctor and include the output in your issue for faster diagnosis
• Set ATLAS_LOG_LEVEL=debug and include relevant log lines