Troubleshooting

A quick reference for diagnosing problems. Find your symptom in the sections below and follow the steps. Each entry links to a deeper guide where relevant.

Build failed

The deployment is marked Failed during the Building phase.

Where to look first: the build log on the failed deployment.

See Deployment troubleshooting for full coverage.

Deployment stuck

A deployment sits in Queued for more than 5 minutes, or in Building / Releasing for far longer than expected.

Steps:

1. Refresh the page — sometimes the UI lags behind the actual status.
2. Open the deployment's log. If there's been no output for several minutes, it's genuinely stuck.
3. Click Cancel on the stuck deployment.
4. Click Deploy again to start a fresh attempt.
5. If the next deployment is also stuck, the issue is on our side — contact support with your service name and the deployment ID.

App crashed after deploy

The deployment went Live, but your app is crashing repeatedly. Your service URL might return 502 or 503 errors, or be slow to respond.

Where to look first: the Logs tab on your service.

Common causes:

• Unhandled exception in code. The log usually shows a stack trace just before each crash.
• Memory limit exceeded. Look for [platform] instance terminated: out of memory lines. See Resource Usage →
• Missing environment variable. Your app reads process.env.X and crashes when X is undefined. See Environment Variables →
• External dependency down. Database, third-party API, etc. The errors will mention the unreachable host.

Immediate mitigation: roll back to the previous working deployment while you investigate.

Service unreachable / URL returns 503

Your URL returns 503 Service Unavailable, the dashboard shows your service is Live, but visitors get nothing.

Possible causes:

• Service paused due to billing. Check Billing — if your wallet ran out, the service was paused at the last renewal. Top up to resume. See Plans & renewal →
• Recent release failed silently. Check Deployments for any Failed row that snuck in. Roll back to a known-good deployment.

Custom domain not working

You've added a custom domain but visitors hit 404, certificate warnings, or the wrong site.

See Custom Domains: troubleshooting for details.

Environment variable missing

Your app says Undefined, Missing, or crashes referencing a config value you thought you set.

Steps:

1. Open your service → Environment Variables tab. Confirm the key exists and has a value.
2. Confirm you saved the change (the variable appears in the list, not just in the form).
3. Redeploy. Variable changes take effect on the next release, not immediately.
4. After redeploy, check the Logs for the new instance starting up. Add a debug log temporarily that prints whether the var is now set (without leaking the value).

If the variable is in the dashboard but your app still doesn't see it, double-check the spelling — process.env.DATABASE_URL is different from process.env.DATABASEURL or process.env.Database_URL.

Service restarted automatically

You see instances restarting in Logs or a brief drop in Resource Usage. Most automatic restarts are normal.

Common reasons:

• Out of memory. Your instance exceeded its memory limit and was replaced. See Resource Usage →
• Health check failed. Your app stopped responding to internal health checks and was replaced. Add a startup log to see how long boot is taking.
• App crashed. Uncaught exception, exit 1, segfault. Logs show the crash reason.
• Platform maintenance. A new instance is started on a different host; traffic is unaffected.

If restarts are frequent and unwanted, look at the Logs for the few seconds just before each restart — that's where the actual cause appears.

Logs not appearing

You opened the Logs tab and see no recent entries.

Steps:

1. Confirm the time range is sensible (default is "Last 5 minutes"; widen to "Last 1 hour" or "Last 24 hours").
2. Confirm the service is actually running. Resource Usage should show ≥ 1 instance.
3. Add a startup log line (console.log('booted')) and redeploy. If that line still doesn't appear, the issue is with log ingestion, not your app — contact support.
4. If your app writes to files instead of stdout/stderr, the logs won't reach the dashboard. Switch to logging to stdout.

Insufficient wallet balance / plan expired

Your service is paused with a "Wallet balance insufficient" or "Plan expired" notice.

Steps:

1. Open Billing → top up enough to cover at least one plan period.
2. Open the paused service → click Resume.

The renewal is retried; your service is back online within a minute.

If you've topped up but the service hasn't resumed:

• Confirm the top-up was successful (check Billing → Payment history).
• Make sure the wallet balance is ≥ the plan's period cost.
• Wait one minute for the next automatic retry, or click Resume again.
• If it still doesn't work, email billing support.

I'm stuck — how do I get help?

Email us and include:

• Your service name (or its default URL).
• The deployment ID from the URL of the affected deployment (looks like dep_xxxxxxxx).
• What you expected to happen.
• What actually happened — copy the last ~20 lines of the relevant log if possible.

We respond within one business day.

Related