Troubleshooting

Troubleshooting

Application does not start

Check that:

• HMAC_KEY and JWT_KEY are at least 32 UTF-8 bytes;
• the SQLite directory is writable, or PostgreSQL is reachable;
• each Redis provider has a connection string;
• provider and failure-mode values are valid;
• port 8080 is available.

Use docker compose logs -f to inspect startup, migration, and connection errors.

MCP key is lost or rejected

A plaintext MCP key is displayed only once. If it is lost, rotate the active key or issue a replacement, update the client, and revoke the old key.

For a rejected key, confirm that it is active, unexpired, assigned to the intended database, and allowed to use the requested tool. See Access Management.

A tool is missing

Tool discovery returns only tools allowed by the authenticated key. Custom tools are filtered by the same allowlist. Edit or replace the key if its scope is incorrect.

HTTP 429

The IP or MCP-key request budget is exhausted. Inspect Retry-After, the startup IP-rate settings, and the key's inherited or custom quota.

HTTP 503 from rate limiting

The Redis limiter is configured FailClosed and Redis is unavailable. Restore connectivity, or deliberately select FailOpen after evaluating the enforcement tradeoff.

Maximum concurrent SQL reached

Inspect MaxConcurrentSql and active workload. In Redis mode, also check Redis connectivity and lease-renewal errors. Leases from crashed instances expire automatically.

Audit logs are empty

Audit records appear after MCP tool execution and administration changes. Confirm that the request reached a tool and that the Admin database is writable. See Operations and Audit.

SQLite data did not appear in PostgreSQL

Changing ADMIN_DATABASE_PROVIDER creates or updates the target schema; it does not copy data between providers. Restore from a planned export/import and verify users, roles, MCP keys, database definitions, policy, and audit records. See Distributed Deployment.