Troubleshooting

Device-code approval opens the wrong page

Production CLI auth should open:

https://auth.atrium.st/activate?user_code=XXXX-XXXX

If you see an API-hosted HTML approval page, the client is using an old flow. The API verify route now redirects to the auth app.

CLI POST gets a trailing slash redirect

CLI OAuth POSTs should target the route without relying on a redirect:

/v0/oauth/device/code
/v0/oauth/token

The auth app does not expose these POST routes. If a client posts to auth.atrium.st, update the CLI or environment override to use the API domain.

atrium validate rejects my env var

Build env is allowlisted. The current placeholder allowlist only contains:

NEXT_PUBLIC_FEATURE_X

Platform-owned env vars such as NEXT_PUBLIC_API_BASE_URL, DATABASE_URL, NEON_DATABASE_URL, and HASURA_GRAPHQL_DATABASE_URL must never be added to atrium.yaml.

Deploy status stays queued

The backend records deployment requests even when no worker is configured. If ATRIUM_DEPLOY_WEBHOOK_URL is not set, status can stay queued. That means the control plane accepted the request but did not dispatch a Cloud Run deploy worker.

Status returns Agent not found

Validation only proves the local manifest shape is valid. It does not prove the agent exists in the control plane.

If status returns:

404 {"detail":"Agent not found"}

the agent needs to be registered first. atrium init registers new agents. For an existing repo, a current atrium deploy dry-run can preview first-time registration with action: "create" when the request includes the manifest.

atrium env returns Service not found

env, logs, and sync use the persisted control-plane manifest. If an agent only has a placeholder manifest in the control plane, dry-run deploy can still preview the real local services while env backend returns:

404 {"detail":"Service not found"}

Run a confirmed deploy only when the agent owner is ready for the manifest to be persisted and a deployment request to be queued.

atrium logs --follow does not stream

The logs endpoint supports recent reads. Backend streaming is not implemented yet, and follow=true returns 501. The CLI should poll for now.

Agent cases are missing on the host

The host treats failed case reads as unavailable data, not a host error. A missing case card can mean:

• the agent does not implement GET /api/cases
• the agent returned 401, 404, or another non-2xx status
• the response shape failed normalization
• the server-side proxy timed out

The installed agent card should still render with ordinary agent metadata.