Troubleshooting

“Health checks did not pass” on the first deploy

Almost always the app isn’t answering where Apprail is looking.

• Listen on 0.0.0.0, not localhost or 127.0.0.1, and on the port in $PORT.
• Check the service’s port matches the app’s. apprail diagnose reports when the image declares a different port and which one to set.
• Make sure the health path (default /) answers 2xx or 3xx without needing a login. If / redirects to a sign-in page on another host or returns 401, set --health to a public endpoint such as /healthz.
• Slow starts: the release must be healthy within five minutes.

apprail diagnose shop/web
apprail services update shop/web --port 3000 --health /healthz --apply production

The process keeps exiting

apprail logs shop/web shows why. Common causes: a missing variable the app requires at start, a database schema that doesn’t exist yet (add a pre-deploy command), or a start command that runs a development server that exits. For workers, the process must keep running — a script that finishes is a job.

Out of memory

The instance used more memory than it has and was restarted. Raise it with apprail services update shop/web --memory 1024. Node.js apps can also cap their heap with NODE_OPTIONS=--max-old-space-size=… set a little below the limit.

“self-signed certificate in certificate chain” connecting to Postgres

Your app is using an older DATABASE_URL with sslmode=require. Redeploy the service to pick up the current URL (sslmode=disable — the connection stays inside the environment’s private network). If you set DATABASE_URL yourself, update it.

A variable change didn’t take effect

Variables you set apply on the next deployment. Redeploy what’s live with apprail services update shop/web --apply production. Check what the service actually receives with apprail variables shop --values.

The build can’t find the branch or Dockerfile

Apprail uses the exact branch, tag, or commit you give it — check the spelling and that it’s pushed. The Dockerfile path is relative to the build context. With no Dockerfile, the framework must be detectable and have a start command (a start script or a Procfile); the build says what’s missing. See Builds.

The build fails installing packages

Apprail falls back from a strict lockfile install to a normal one, so a drifted lockfile isn’t fatal. If installs still fail, check that private packages have credentials available at build time (use a Dockerfile), and that the build fits in 30 minutes and 4 GB of memory.

The image can’t be pulled

Check the image name and tag. For a private registry, add a credential for its host with apprail registries add; deployments from that host use it automatically.

A deployment is stuck waiting

In a protected environment it waits for approval (awaiting_approval): an owner or admin approves it in the console. apprail deploy --detach leaves it waiting without blocking your terminal.

“quota_exceeded”

The change would take the workspace past a limit. The message says which limit, what’s in use, and what the change needed. Shrink or delete something, or ask for a higher limit.

A domain stays pending

Compare the records at your DNS provider with apprail domains shop/web — both the CNAME and the validation records. DNS changes can take a while to spread. A root domain needs CNAME flattening or an ALIAS record. If the hostname is taken by another workspace’s abandoned claim, you’ll be told to retry in a minute while it’s released.

“No room to start an instance”

The region couldn’t fit a new instance of that size right now. The service keeps serving on the instances it has. Try smaller instances or fewer of them.

databases connect is refused

Tunnels need a full-access token from a member who can change the project; read and deploy tokens can’t open them. Create a suitable token and run apprail login again.