Troubleshooting
Diagnose authentication, provider, routing, storage, and runtime failures.
Start with the part of the system that owns the failed behavior. Browser rendering belongs to the workspace UI, authentication and provider policy belong to the API service, and repository commands belong to the secure runner.
Authentication
OAuth returns to the landing page: verify FRONTEND_URL points to the public agents path and GITHUB_REDIRECT_URI matches the callback registered with GitHub.
Session stays unauthenticated: inspect the response from /auth/session, cookie attributes, and allowed origins. Do not debug this by storing an OAuth token in browser storage.
Approved GitHub user is still redirected to Cloud: confirm the production allowlist contains the exact GitHub login. Matching is case-insensitive, but stale deployments or missing environment variables can keep the old list active.
Providers
Credential validation fails: confirm the credential belongs to the selected provider, has not been revoked, and can reach the provider API from the deployed environment.
A model is missing: refresh the provider catalog and check account access. Hidden, coming-soon, or transport-incompatible models are intentionally omitted.
Execution is rejected: the selected model may lack the capabilities required by the run. Choose another model or provider and retry the task.
Routing
/agents/ shows landing HTML: verify the landing Pages Function exists at functions/agents/[[path]].ts and AGENTS_ORIGIN points to the agents project.
Agents JavaScript returns HTML: confirm the public /agents/assets/... path is stripped to the upstream /assets/... path by the proxy and that Web was built with base /agents/.
Docs link returns 404: verify /docs/*, including /docs/changelog/, is routed to the docs static output by the production edge configuration.
Runtime and storage
Run commands hit the wrong service: check MUSCLE_BASE_URL locally and compare runtime fingerprint endpoints on ports 8787 and 8788.
Database operations fail immediately: verify the database binding and connection string for the API service.
A migration fails: stop deployment, inspect the exact migration and statement number, and verify the migration ledger. Do not mark a failed migration as applied manually.
Keep correlation identifiers
When reporting a runtime failure, include the run identifier, correlation identifier, endpoint, status code, and sanitized error message. Never include tokens, provider keys, or repository contents.