Troubleshooting

Common issues and solutions when running Stategraph.

Deployment Issues

Container won't start

Symptoms: Server container exits immediately or keeps restarting.

Check logs:

docker compose logs server

Missing required environment variables

Error: Key_error "STATEGRAPH_UI_BASE"

Solution:
- Set all required environment variables (see Environment Variables)

Database connection failed

Error: Could not connect to database

Solution:
- Verify database is running and credentials are correct

Port already in use

Error: bind: address already in use

Solution:
- Stop the service using the port or change STATEGRAPH_PORT

Database connection errors

Symptoms: Server starts but can't connect to PostgreSQL.

Checklist:

• PostgreSQL container is healthy: docker compose ps
• DB_HOST matches the service name (e.g., db for Docker Compose)
• DB_PORT is correct (default: 5432)
• DB_USER, DB_PASS, DB_NAME match PostgreSQL configuration
• Network connectivity between containers

Test connection:

docker compose exec server nc -zv db 5432

Health check failing

Symptoms: Container marked unhealthy, restarts repeatedly.

Check health endpoint:

curl http://localhost:8080/api/v1/health

Common causes:
- Database not ready yet (increase depends_on timeout)
- Port mismatch between health check and actual port
- Internal service not starting

Authentication Issues

OAuth redirect errors

"redirect_uri_mismatch"

The callback URL doesn't match your OAuth provider configuration.

Solution:
1. Check STATEGRAPH_UI_BASE matches your access URL exactly
2. Add exact callback URL to OAuth provider:
- For Google: {STATEGRAPH_UI_BASE}/oauth2/google/callback
- For OIDC: {STATEGRAPH_UI_BASE}/oauth2/oidc/callback
3. Verify protocol (http vs https) matches

"invalid_client"

Client ID or secret is incorrect.

Solution:
- Verify credentials from OAuth provider dashboard
- Check for extra whitespace or newlines
- Regenerate secret if needed

Session not persisting

Symptoms: Login succeeds but immediately redirects back to login.

Causes:
1. URL mismatch: STATEGRAPH_UI_BASE differs from access URL
2. Cookie not set: Proxy stripping cookies, or SameSite issues
3. HTTPS mismatch: Accessing via http when configured for https

Solutions:
- Verify STATEGRAPH_UI_BASE exactly matches your browser URL
- Check for reverse proxy cookie handling
- Use consistent protocol

Login fails with "invalid CSRF token" (multi-replica)

Symptoms: Login intermittently fails at the OAuth callback with
403 Forbidden — Unable to find a valid CSRF token. It may succeed on one
attempt and fail on the next, and often breaks after a restart or scale-up.

Cause: With more than one replica, each replica signs the OAuth
session/CSRF cookies with its own secret unless a shared one is configured. When
/oauth2/start and the OAuth callback are load-balanced to different replicas,
the callback replica can't validate the cookie the first one issued.

Solutions:
- Set STATEGRAPH_OAUTH_COOKIE_SECRET to the same value (16/24/32 chars) on
every replica so any replica can validate the cookie. This also keeps users
logged in across restarts. (Helm/Terraform users: the chart and the ECS
module generate and share a stable value automatically.)
- As a stopgap, enable session affinity (sticky sessions) on your load balancer
so a client's whole OAuth flow lands on one replica.

"Access denied" after authentication

Causes:
1. Email domain restriction: User email not in allowed domain
2. Google Groups: User not in required group
3. OAuth app not approved in organization

Solutions:
- Check STATEGRAPH_OAUTH_EMAIL_DOMAIN setting
- Verify group membership (Google Groups)
- Request app approval from organization admin

Terraform Backend Issues

"Failed to get existing workspaces"

Symptoms: terraform init fails with HTTP error.

Causes:
1. Stategraph server not running
2. URL incorrect
3. Network connectivity
4. Authentication failure

Solutions:

# Test connectivity
curl http://localhost:8080/api/v1/health

# Test with credentials
curl -H "Authorization: Bearer $STATEGRAPH_API_KEY" http://localhost:8080/api/v1/whoami

Transaction conflict (TX_CONFLICT, HTTP 409)

Symptoms: A commit fails because another transaction touched overlapping resources. Stategraph's
HTTP backend does not implement Terraform's lock/unlock, so terraform force-unlock does not
apply — concurrency is managed by transactions.

Solutions:
1. Wait for the in-flight transaction to complete, then retry
2. If a transaction is stuck, abort it:
bash stategraph tx abort --tx <tx-id>
3. List open transactions to find the ID: stategraph tx list --tenant <tenant-id>

"HTTP error: 401 Unauthorized"

Causes:
1. API key invalid or expired
2. Username not set to session
3. Token has leading/trailing whitespace

Solutions:
- Create a new API key
- Verify username = "session" in backend config
- Check token value for whitespace

Large state timeout

Symptoms: Operations fail for large state files.

Solutions:
1. Increase STATEGRAPH_CLIENT_MAX_BODY_SIZE (default: 512m)
2. Check reverse proxy timeouts
3. Consider splitting state into smaller files

"command not found" running plan or apply

Symptoms: stategraph tf plan or stategraph tf apply exits immediately without running Terraform or OpenTofu.

Error message

Error: tofu: command not found. Install OpenTofu or Terraform, or set the TF_CMD environment variable to your binary.

Solution:

• Install OpenTofu or Terraform and make sure it is on your PATH
• Or set TF_CMD to the full path of your tofu or terraform binary

Plan appears to hang

Symptoms: stategraph tf plan stops making progress and never finishes, producing no further output.

Cause: Terraform or OpenTofu is waiting for an interactive answer (for example an input variable prompt), but no human is attached to respond.

Solution:

• Supply every required variable non-interactively with -var, a *.tfvars file, or TF_VAR_* environment variables so nothing prompts
• Upgrade to the latest CLI, which detects an unanswered prompt instead of hanging

"has not been declared" during plan

Symptoms: stategraph tf plan fails while evaluating your configuration.

Error message

An input variable with the name "..." has not been declared.

(a Local value with the name "..." has not been declared. variant can appear the same way)

Solution:

• Trace exactly how Stategraph evaluates the module with stategraph diagnostics run <dir>, which walks the root module directory and writes an evaluation trace (to stderr, or to a file with --out). Pass --var / --var-file and --workspace to match the inputs and workspace your plan uses
• Confirm the referenced variable or local is actually declared in the evaluated module, and that its source module resolves as expected
• Upgrade to the latest CLI — several evaluation fixes for this error shipped in recent releases

UI Issues

Page won't load

Symptoms: Browser shows blank page or error.

Check:
1. Browser developer console for JavaScript errors
2. Network tab for failed requests
3. Server logs for backend errors

Solutions:
- Clear browser cache
- Try incognito/private mode
- Check CORS settings if UI is separate

Query returns no results

Symptoms: SQL query runs but returns empty.

Causes:
1. No matching data
2. Query syntax issue
3. Wrong table or column names

Debug steps:

-- Verify data exists
SELECT count(*) FROM instances

-- Check available types
SELECT DISTINCT type FROM resources ORDER BY type

-- Simplify query
SELECT * FROM instances LIMIT 10

Graph won't render

Symptoms: Dependency graph blank or shows error.

Causes:
1. State has no resources
2. Very large state causing performance issues
3. Browser memory limitations

Solutions:
- Check state has resources in the list view
- Apply filters to reduce graph size
- Try a different browser

Performance Issues

Slow queries

Symptoms: SQL queries take long to execute.

Solutions:
1. Add LIMIT clause:
sql SELECT * FROM instances LIMIT 100
2. Use specific columns instead of *
3. Add filters early in query
4. Check database indexes

High memory usage

Causes:
1. Large state files
2. Many concurrent connections
3. Memory leak (report as bug)

Solutions:
- Increase container memory limits
- Reduce DB_MAX_POOL_SIZE
- Monitor and restart periodically if needed

Database connection exhaustion

Symptoms: "too many connections" errors.

Solutions:
1. Reduce DB_MAX_POOL_SIZE
2. Increase PostgreSQL max_connections
3. Check for connection leaks

Gap Analysis Issues

"Not ready for gap analysis"

Symptoms: Gap analysis reports not ready.

Causes:
1. AWS Config not enabled
2. Aggregator not configured
3. Missing IAM permissions

Solutions:
- Enable AWS Config in your account
- Create a configuration aggregator
- Grant Stategraph required permissions

AWS resources not appearing

Causes:
1. AWS Config not recording resource types
2. Aggregator missing regions
3. Stale cache

Solutions:
- Verify AWS Config recording settings
- Check aggregator configuration
- Use source=no-cache to force refresh

Cost Analysis Issues

Cost analysis disabled or returns 503

Symptoms: capabilities.costs.enabled is false, POST .../costs/calculate returns 503, or
cost analysis worked and then disappeared after a redeploy, restart, or pod/task reschedule.

Cause: The server booted without STATEGRAPH_COST_ENABLED=true set in its environment — for
example it was added to one container but not to the deployment config, so a recreated or
rescheduled container came up without it.

Solution:
- Set STATEGRAPH_COST_ENABLED=true durably in your deployment environment (Compose .env /
environment:, Kubernetes Deployment env, or the ECS task definition), then redeploy.
- See Cost Setup for the durable enablement steps and verification.

Getting Help

Collect diagnostic information

Before reporting issues, gather:

1. Server logs:
   bash docker compose logs server > server.log 2>&1

2. Environment (redact secrets):
   bash docker compose config

3. Version information:
   bash docker compose images

4. Health check output:
   bash curl http://localhost:8080/api/v1/health

Reporting issues

Report issues at: https://github.com/stategraph/releases/issues

Include:
- Description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Diagnostic information (above)
- Screenshots if applicable

Common Error Messages