# A deploy failed

> The Deploys tab says "Last deploy failed". Read where it stopped and why, then fix the cause and deploy again.

Source: https://veldhost.eu/docs/deploy-failed

Last verified: 2026-11-13

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:

| Step | What fails here |
| --- | --- |
| **Waiting for a build machine** | No build machine picked the deploy up within 15 minutes, or one took it and never began it within 60 minutes. |
| **Checking the repository layout** | The repository is laid out in a way we cannot publish, for example the app sits in a subfolder or the files visitors load are not in `public/`. |
| **Fetching your code** | The branch or tag does not exist, the repository moved, or we are not allowed to read it. |
| **Installing dependencies** | `npm ci` or Composer cannot install, often because the lock file is out of date. |
| **Building** | Your build command exits with an error. |
| **Running your tests** | Your test command exits non-zero. |
| **Publishing the release** | The build produced nothing, or there is no `public/` folder to serve. |
| **Running database migrations** | A migration fails against the live database. The new release is not switched on. |
| **Switching your site to the new release** | A release you approved could not be put live, or it is no longer on the server. |
| **Checking the site after the switch** | Right after the switch, your site answered with a server error (500, 502, 504 and so on) or not at all. A Node.js app must also start and answer on its port. Any other answer counts, including a 404 or a login page. |

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](https://veldhost.eu/docs/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](https://veldhost.eu/docs/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](https://veldhost.eu/docs/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](https://veldhost.eu/docs/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](https://veldhost.eu/docs/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](https://veldhost.eu/docs/502-after-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](https://veldhost.eu/contact) with them and the site name.

## Related

- [Deploy from Git](https://veldhost.eu/docs/deploy-from-git)
- [Build steps](https://veldhost.eu/docs/build-steps)
- [Approve a release, discard it or roll back](https://veldhost.eu/docs/release-approval-and-rollback)
- ["502 Bad Gateway" after a deploy](https://veldhost.eu/docs/502-after-deploy)