Troubleshooting

Start at the runtime boundary that failed, capture sanitized evidence, and account for process-local state.

Health checks

text

FastAPI: GET /api/health
Engine:  GET /health
Engine:  GET /ready   # requires a loaded catalog

Authentication and proxy

Verify API_URL, matching KAVEON_PROXY_SECRET values, AUTH_URL, and provider callback URLs. Set WEB_URL to the exact Studio origin. Never expose the proxy secret to browser code.

Database connectivity

Check the METADATA_* settings, DNS/firewall access, TLS, driver installation, and database role. A registered source’s test endpoint is a stub; run SELECT 1 in SQL Lab or use a setup/admin probe.

Expected alpha behavior

Workers execute versioned distributed fragments, but admission control and aggregate/join spill are not yet implemented.
Engine query history and FastAPI job/cache state are process-local and disappear after restart.
Query cancellation propagates to active distributed work, but synchronous operators only observe cancellation at their current execution boundaries.
ADLS Gen2, S3, Iceberg, and external catalog adapters are contracts rather than executable data paths.

Escalation

Record commit, component, timestamp/time zone, route or sanitized SQL, database type, topology, and restart behavior. Never publish tokens, .env, connection strings, or customer rows.