Troubleshooting & FAQ

Requests return HTTP 402

402 means the app is paused for billing, not that it crashed. On the Free plan it happens when the month's usage reaches the included $1: apps resume on the 1st of next month, or straight away when you upgrade. On a paid plan it means your prepaid credit ran out: apps resume automatically after a top-up. Both are in Dashboard → Billing & usage. The API also returns 402 when an action needs credit you don't have, such as upgrading from your balance.

A deploy failed

A failed release never takes traffic. If an earlier release was running, it keeps serving and the app shows v2 failed … still serving v1. Open the app in the dashboard to see which step failed and the last log lines, or run aloof releases <app>. The usual causes, in order:

Wrong port: the app has to listen on 0.0.0.0:$PORT (default 8080), and --port or internal_port has to match. Listening on 127.0.0.1 fails the readiness check.
Health path: if you set one with aloof health <app> --path /healthz, it must return a 2xx/3xx status within a few seconds of starting.
The release command failed (see below).
Image or repo can't be pulled: for private sources, run aloof registry login or set up a deploy key.
The build failed: see build logs below.

After fixing it, deploy again or press Retry deploy on the app. To go back to a known-good version without rebuilding, run aloof rollback <app>.

Diagnose: GET /v1/apps/<app>/diagnose (or the diagnose_app MCP tool) returns recent error log lines, failed health checks, recent deploys, rollbacks and restarts, instance states and exit codes, and likely causes with a suggested fix. It is read-only and redacts secrets and env values.

Where are the build logs?

Build and deploy output is recorded as platform events. You'll find it in the deploy panel on the app's page in the dashboard (shown while a deploy runs and when it fails), under the app's Logs tab, and with aloof logs <app> (the platform events section). The build step stores the last 40 lines of docker build output when the build finishes, so you'll see them in one batch rather than line by line.

What happens when the release command fails?

release_command (for example database migrations) runs once, in a separate machine, after the build and before any new instance starts. If it exits with a non-zero code, the deploy stops: no new instances start, the release is marked failed, the previous release keeps serving, and the last 30 lines of its output are in the logs prefixed with [release]. Fix the command and deploy again. Make migrations safe to run twice, because a retry runs them again.

A short gap during a deploy

Apps with a volume attached are single-writer, so the old instance stops before the new one starts, which causes a brief gap. Apps without a volume roll with no downtime.

Custom domain won't verify

See Custom domains → If verify fails. Cloudflare users: set the records to DNS only.

Can't reach Postgres from my laptop

Databases are private. Use aloof proxy 5432 -a pg-<name>; see Managed Postgres.

Still stuck?

Support doesn't have a public email address yet; see Support for where things stand.