Troubleshooting

Start with context

Record the CLI version, selected workspace, app slug, service name, and operation or deployment ID. Use atrium --version, atrium status, and the API's GET /v0/platform/me as appropriate. Remove credentials and customer data from diagnostics before sharing them.

Sign-in or workspace errors

atrium login opens device approval on auth.atrium.st. OAuth token requests go to https://api.atrium.st/v0/oauth/token, not the browser sign-in host.

For an expired device code, start a new login. For an expired access token, refresh or sign in again. For 403, verify workspace membership and the token's selected workspace before repeating login. Browser workspace switching does not automatically replace an existing CLI access token.

See Authentication and Team access.

App redirects to pricing or denies access

Check enrollment in the currently selected workspace. Free requires an explicit enrollment, and publisher membership does not bypass subscription-protected routes.

For an unexpected denial on a public page, inspect overlapping access rules. A public rule does not override a matching rule with higher precedence. Also check assets, trailing slashes, and HTTP methods. See App access.

A checkout return URL is not proof of an active entitlement. Confirm the server-side subscription state and avoid duplicate purchases while fulfillment is pending.

Manifest or service is not found

atrium validate checks the local manifest; it does not register an app. Offline scaffolding also skips registration. Deploy the intended manifest or register it through the API.

Use actual service keys, not service types: a Hasura service named gql is addressed as gql, not automatically as database. If a local service is absent from resolved state, inspect the persisted manifest and latest deployment result.

For a rejected environment value, check the public schema's allowlist and reserved fields. Do not work around validation by committing credentials. See Manifest schema.

Local development session fails

Use atrium dev status to inspect the session, and atrium dev stop to revoke it when finished. An expired or revoked session must be replaced. Use atrium dev --fresh when you intentionally need a new session, then restart local processes with the new environment.

Check the selected services, requested TTL, installed dependencies, and workspace access. An isolated database needs additional platform setup; it is not guaranteed by choosing the Hasura starter. Ask Atrium to confirm availability rather than copying production database credentials.

If you refreshed a session through the API, restart processes that need the new values. Session refresh does not rewrite a running process's environment. See Local development.

Deployment stays queued or following stops

A queued record means the request was accepted, not that the app is live. Inspect the deployment in Studio or use atrium deployments and atrium status.

The CLI follows for 600 seconds by default. A follower timeout or disconnect does not cancel the build. Resume inspection using the deployment ID; increase --follow-timeout when appropriate. If no build progress appears, contact Atrium with the ID and timestamp. Platform setup may need attention.

Upload, build, migration, or startup failure

Stage	Check
Source upload	Non-empty gzip archive, size under 200 MiB, valid workspace access.
Image build	Included source files, service paths, Dockerfiles, dependencies, and build output.
Database migration	Existing database/Hasura setup and migration ordering.
Metadata	References to schema objects created by preceding migrations.
Service startup	Health endpoint, listening configuration, and required runtime environment.
Routing	Successful deployment result and the returned public URL.

Inspect the failed stage before submitting another deployment. A failed build does not roll back SQL that already ran or necessarily revert application services already updated. Keep migrations compatible with the currently serving app. See Deployments and Databases and migrations.

For an expired migration token, request a new scoped session, verify the operation's current state, and continue safely. A new token does not make a non-idempotent backfill safe to repeat.

Logs look empty or follow is quiet

Recent log reads and deployment-event streams are different. atrium logs frontend --follow follows deployment events; it is not a continuous tail of all application output.

Before the first deployment, logs can be empty. Check the service key, deployment selection, cursor, and source-availability information in the API response. Runtime log availability can differ from deployment-event availability. See the API reference.

Entitlement or quota checks fail

Use require for feature access, balance for numeric usage, and consume for a metered unit of work. A true require result does not prove quota remains. Use the app SID or UUID in billing requests, not the slug, and verify the customer's selected workspace.

Retry the same consumption attempt with the same idempotency key; use a new key only for new work. Check the plan's quota period. Monthly quotas reset by UTC calendar month, not billing anniversary.

For one-time credit purchases, unresolved fulfillment and combined-credit consumption issues remain. Do not assume a successful checkout means credits were reliably delivered. See Billing and entitlements.

Home cases or Studio updates are missing

For missing cases, check GET /api/cases authentication, response shape, and endpoint availability. Verify that returned records belong to the selected workspace. An app without case support can still launch.

For Studio listing edits, wait for autosave completion and inspect any save error before leaving. Listing updates do not deploy source or establish automatic repository synchronization. See AgentCase and Studio.