Troubleshooting App Platform

Most App Platform problems fall into a few patterns: the build fails, the build succeeds but the site doesn't answer, nothing has ever deployed, or the app keeps stopping. This guide tells you where to look first for each one, and when to stop retrying and contact us.

1. Start here

2. The app builds but won't load

The usual cause is how the app listens. It must:

• listen on the port in the PORT environment variable, never a hard-coded number;
• bind to 0.0.0.0, not localhost or 127.0.0.1. An app bound to localhost can't be reached from outside its container.

// Node.js
const port = process.env.PORT || 3000;
app.listen(port, '0.0.0.0');

For a Dockerfile app, pass the same values to your server's start command. For example, a Python app served by Gunicorn:

CMD gunicorn app:app --bind 0.0.0.0:$PORT

If the Logs tab shows the app started and is listening on 0.0.0.0 at the right port, and the address still doesn't answer, stop and open a ticket. That combination points to routing on our side, and redeploying won't fix it.

3. The build fails

Open the failed deploy in the Deploys tab and read the build log from the bottom up; the line that broke the build is usually near the end. Common causes:

• No language signal in the project root. Only Node.js is detected automatically, from a package.json in the root of the archive or repository. Python, PHP and every other language need a Dockerfile in the root.
• Files packed one folder too deep. If you deploy with a token, package the contents of your project with tar czf app.tar.gz -C my-app . so package.json or Dockerfile sits at the top of the archive.
• Wrong Node.js version. Pin the version your app needs in package.json, for example "engines": { "node": "22.x" }.
• Private npm packages without an auth token available to the build.
• An error in your Dockerfile. The build log shows the step that failed.

If the deploy shows "Not started: platform busy", nothing was built because the platform was building other apps. Deploy again in a few minutes.

4. Nothing has deployed at all

If the Deploys tab says "No Deployments Yet", your code has never reached us, so there's no build log and nothing in your code is at fault yet.

• Using GitHub? Check the GitHub tab shows your repository and branch, then click Deploy Now. Pushing to GitHub does not deploy by itself.
• Using a deploy token? Run the upload command again and read the error it prints. The table in section 5 explains each one.

5. Deploy-token errors

A token works for one app only, so pointing it at another app is reported as an invalid token. The Deploy Tokens tab shows a ready-to-run command with your token and app already filled in when you create a token. Copy that command rather than editing an example. If it still fails, open a ticket with your app name; never send us the token itself.

6. The app keeps stopping or restarting

A crashed app restarts automatically. If it keeps stopping:

• Read the last lines in Logs before each stop. Common causes are an unhandled exception at startup or a missing environment variable.
• Check Overview › Metrics for memory use. Each app has a fixed 512 MB memory limit on every plan, and a higher plan gives you more apps, not more memory per app. If one app needs more than 512 MB, reduce its memory use or talk to us.
• If the Overview says "This app stopped without being asked to", try Restart. If it keeps stopping, the Logs tab shows why.

7. 502 or 503 errors

• The app is still starting. Wait a moment and reload.
• The app crashed. Check Logs.
• Wrong port or bound to localhost. See section 2.
• Web processes scaled to 0. In Configure › Scale, a web process set to 0 stops the app answering, and visitors get a 503. Set it back to 1 or more.

8. Environment variables and files

• A variable doesn't take effect: check the name and capitalisation in the Env Vars tab. Saving a variable restarts the app; confirm in Logs that it restarted cleanly. See Environment variables.
• "Cannot modify system variable": DATABASE_URL is managed by the platform. Put your own value in a variable with another name.
• Uploaded files vanish after a deploy: the app's filesystem is rebuilt on every deploy. Attach a folder in Data › Storage for anything that must survive a redeploy, then restart or redeploy.

9. Still stuck?

Open a ticket at /client/support/new or /support/ticket and include your app name, what you expected and what happened, and the error text from Logs or the failed build. Never paste a deploy token, access token or password into a ticket.

Ready to get back online? Open your App Platform apps, read the App Platform overview, or ask us in a support ticket.