Deployment Failed? How to Find and Fix the Cause

Your GitHub authorisation expired or was removed. Open the project’s deploy guide, click Reconnect GitHub, and deploy again.

The branch was renamed or deleted, for example master to main. Reconnect the repository with the right branch.

The repository was renamed, moved to another account, deleted, or made private after you connected it as a public repository. Reconnect it.

Your app was recognised, but not how to start it. This is typical for Python apps. Add a Procfile with a web: line, as shown in the Python guide. For Node.js, add a start script to package.json.

Nothing the platform recognises was found where it looked. Check Build context points at the folder containing your app’s package.json, requirements.txt or similar. If your stack isn’t detected automatically, add a Dockerfile: see How to Deploy Any App with a Dockerfile.

Your build command exited with an error. Read the build log from the bottom up. The usual suspects are a package missing from package.json or requirements.txt, a TypeScript or lint error, or a step that needs a variable you haven’t set. Try the same build on your computer: npm ci && npm run build, or docker build . for a Dockerfile.

Run npm install on your computer, commit the updated lockfile and push. The same goes for yarn.lock and pnpm-lock.yaml.

Builds run in CI mode, where Create React App stops on lint warnings. Fix the warnings, or change the build script to CI=false react-scripts build.

Large JavaScript builds, particularly Next.js, Nuxt and Strapi, can need more memory than Node.js allows itself by default. Raise the limit for the build only:

"build": "NODE_OPTIONS=--max-old-space-size=1536 next build"

Set it in the build script rather than on the Environment tab, which would also apply it to your running app. If the build still runs out, get in touch.

A temporary problem storing your build. Deploy again; it almost always goes through.

The build worked, but your app either crashed on start or never answered its health check. Open the Logs tab, then work down this list:

• A crash on start. Look for an error in the logs, often a required environment variable that isn’t set or a database that can’t be reached.
• Listening on localhost. Your server must listen on 0.0.0.0. Fastify, Flask’s development server and uvicorn all default to localhost.
• The wrong port. Your app should listen on the PORT environment variable. If it’s hard-coded, click Deploy at the top of your project and set Container port in the Configure step to match.
• The health check path fails. It must answer with a success response. A path that doesn’t exist (404), needs a login, or errors (500) fails. Change it, in the same Configure step, to a route that always answers, such as /health.
• Django’s host check. Django rejects the health check with a 400 unless it’s answered before ALLOWED_HOSTS is checked. The Python guide has a small fix.

Your app took too long to start or to pass its health check. Check the logs for a slow start, such as long migrations or a large cache being built, and move heavy work out of startup where you can.

Your project’s CPU or memory allocation is too small for the number of copies your plan runs. Contact support to have the project’s resources raised, or upgrade your plan.

Each plan includes a number of deployments per day. The count resets at midnight (UTC), or upgrade your plan for a higher limit. Rolling back counts as a deployment too.

Deploys pause while a plan is suspended, usually for an unpaid invoice. Nothing has been deleted: settle the invoice in the billing portal, and deploys resume.

For security, apps connect out to the internet on ports 80 and 443 (websites and HTTPS APIs) and 5432 (PostgreSQL) only. Services on other ports, such as email over SMTP or an external MySQL server, can’t be reached. Send email through your email provider’s HTTPS API instead, and use a managed database for MySQL-style data.

If the variable is marked Build on the Environment tab, its value was baked in when your app was built. Redeploy to rebuild with the new value. Frontend variables such as VITE_ and NEXT_PUBLIC_ always work this way.

Your app runs as two copies, and each redeploy starts fresh ones. Sessions kept in memory and files written to local disk aren’t shared between copies and don’t survive a deploy. Keep them in a database or external storage.