A deploy failed

Your site's Deploys tab shows Last deploy failed, or a row in Recent deploys is marked failed. We read the build log for you. The failure line says where the deploy stopped, why, and what to do Next:. The Log link on the row opens the full output.

Why it happens

A deploy from Git runs these steps, roughly in this order. The failure names the step it stopped at:

Your build and your tests run on a separate build machine, so a failure there never reaches your visitors. When the message says "Your site is unchanged.", nothing changed.

Running database migrations and Checking the site after the switch are different:

• A failed migration stops the deploy before the switch, so visitors keep the release they had. A migration can stop halfway, though, and what it already changed in your database stays changed.
• A failed check switches your site back to the release it was on, and the deploy is marked failed. Migrations that already ran are not undone. With no earlier release to go back to (a first deploy, or code updated in place with Build & deploy), the new code stays live: its row in Recent deploys reads live, failing, and the Live now strip names it.

Fix it

Start with the failure line. It is on the Deploys tab, next to Live now, and in the drawer under the failed row.

1. "The branch or tag … does not exist" or "We were not allowed to read the repository." Check the branch under Deploy from Git; it is case-sensitive. A private repository needs its Git host connected, or the deploy key shown there added to the repository. See Deploy from Git.
2. "The repository has no public/ folder at its top level", or a message about where the repository keeps its app (Checking the repository layout). Open Repository layout under Deploy from Git and confirm the app folder and web root, or move the files as the message says.
3. "npm could not install your JavaScript dependencies" or "Composer could not install your PHP dependencies." Run the same install on your computer, commit the updated package-lock.json or composer.lock, and push. "Your code needs PHP X, and this site runs PHP Y": change the version under Configure → PHP version (Switching PHP versions), or relax the requirement in composer.json.
4. "Your front-end build failed" or "Your tests failed, so nothing was published." Run npm ci, then your build or test command, on your computer and fix what it reports. To change the commands themselves, open Edit build steps on the Deploys tab (Build steps).
5. "A database migration failed." When the line goes on "so the new release was not activated", your site is still on the release it was on. Run the migration on your computer against a copy of the data, fix it and push. A migration can stop halfway, so check the site and its Logs too. For a deploy held for approval, migrations only run when you approve it, and a failed one stops the release going live.
6. "The deploy ran out of memory and was stopped." The build machine has a fixed memory budget, the same on every plan, so a bigger plan does not help. Make the build lighter: switch off source maps, drop unused heavy dependencies, or split a very large build. When the log says JavaScript heap out of memory, you can also give Node.js more room in your build command under Edit build steps, for example NODE_OPTIONS=--max-old-space-size=1536 npm run build. See "Allowed memory size exhausted" / out of memory.
7. "The new release was built, but your site gave server errors (or no answer) …" When the line ends "so we switched it back to the release it was on", visitors are already back on the previous release. Otherwise the new code is live: roll back first if visitors are affected, with Roll back to … on the Live now strip. Either way, open the Logs tab for the error (Reading your site logs), fix it and deploy again. For a Node.js app, a start command that crashes or listens on the wrong port fails here too; see "502 Bad Gateway" after a deploy.
8. "We could not publish the release you approved.", "… is no longer on the server", "The database migrations for this release failed …" or "This release did not answer after the switch …" Your site is on the release it was on. Fix the cause the message names and deploy again to build a fresh release. "This release is live but did not answer after the switch …" is different: there was no earlier release to go back to, so the release you approved is live and failing. Open the Logs tab for the error, fix it and deploy again.
9. "The deploy did not start — please try again or contact support." No build machine picked it up within 15 minutes. Press Redeploy on the Live now strip, or Deploy from Git. If it happens twice, contact us; that part is ours to fix.
10. "A build machine took this deploy but never began it …" The build machine works through its deploys one after another, and this one was still waiting its turn 60 minutes later. Nothing changed on your site. Deploy again; if it happens twice, contact us.
11. "The deploy started but stopped reporting progress …" A build machine took the deploy, then said nothing more for 60 minutes. It may not have finished. Check your site and the Log, then deploy again. A build that hangs on a prompt or a network call ends like this; if it happens twice, contact us.
12. "Our deploy tooling failed on our side." Nothing to change in your code. We have been alerted. Deploy again once we confirm the fix.

When the line reads "The deploy stopped. The last thing it said was: …", there was no specific match. Open Log and read the last ten lines or so; the first error there is usually the cause.

Tip: Most build and install failures come from a project that builds on your computer only because of something not committed: a lock file, an .env value, a generated file. A fresh git clone into an empty folder, then your install and build commands, reproduces our build.

Still stuck?

Copy the failure line and the last 20 lines of the Log. Contact us with them and the site name.

Related

• Deploy from Git
• Build steps
• Approve a release, discard it or roll back
• "502 Bad Gateway" after a deploy