SupportConsole
llms.txtSign in

Find out why a deployment failed and fix it

llms.txt

A red Failed badge on a deployment means something in the sequence stopped it: fetching the code, a command in your deploy script, or the health check that SrvYard runs after the new release goes live. The output of the deployment always says which, and usually in the first error line.

This article shows how to find that line quickly, how to use the explanation SrvYard writes for you, the failures people meet most often with the fix for each, and how to get a broken release off your visitors while you repair it.

Before you begin

  • View access to the site to read a deployment, and the right to deploy (sites:manage-deploys) to redeploy or roll back. See Roles and permissions.
  • A rough idea of what changed. Was it a new commit, a dependency update, a changed .env, a new PHP version? Most failures come from the last change.
  • Patience with the order of events. A deployment fetches the code into a new release, links shared paths (.env, storage), runs your deploy script, switches the site to the new release, and only then runs the health check. The step where it stopped decides what is live.
Note

On a zero-downtime site the new release is switched in only after your script succeeds. A failure in the code fetch or the script leaves the previous release serving visitors. A failed health check is different: the release is already live. The deployment is marked failed, but nothing is rolled back for you. See step 5.

1. Find the failed deployment

Open the site and choose Deployments. Under History, the Status filter narrows the list.

The deployment history filtered by Failed
Filter the history by status to find the failed run.
  1. Status. Choose Failed (the other values are Queued, Running, Finished and Cancelled). The filter shows next to the button.
  2. The failed row. Shows the commit message, hash, branch and author, the Trigger (Push, Manual, Deploy hook, Rollback), the release name, when it started and how long it ran. A very short duration means it failed early: a fetch or authentication problem. A long one that stops near 13 minutes is the script timeout.
  3. Reset. Clears the filter.

Open the actions menu at the end of the row.

The actions menu of a failed deployment
Open the actions menu of the row and choose View output.
  1. Actions. The three dots at the end of the row.
  2. View output. Opens the output in a panel, without leaving the list.
  3. Roll back to this. Greyed out for a failed deployment: only a finished deployment that still has its release can be rolled back to. View deployment (above it) opens the full details page.

2. Read the output from the first error

Choose View output.

The output of a deployment that failed in composer install
The first error in the output is the cause; the lines after it are consequences.
  1. The summary. The red box repeats the error SrvYard recorded: composer install failed: Your lock file does not contain a compatible set of packages.
  2. Follow, Copy and Download. Follow keeps the view at the end of a running deployment; turn it off to scroll up. Copy and Download are for support or for a teammate.
  3. The log. Read from the top. The lines up to Running the deploy script are SrvYard's own steps (clone, link shared paths). Below them is the output of your script. Look for the first line that says what went wrong; here Problem 1 states that composer.json requires PHP ^8.4 while the site runs 8.3.12.
Tip

Look at the first error, not the last line. The last line is nearly always the generic Deployment failed., and everything between the real error and that line is fallout.

Secrets are masked when a line is written, but the output can still contain paths and names, so check it before pasting it into a public issue.

3. Let SrvYard explain it

Choose View deployment for the details page. Under the red banner The deployment failed you find the card Why it failed.

The Why it failed card on the deployment details page
The details page explains the failure and suggests a fix; check it before you act.
  1. The banner. The same one-line error as before.
  2. Confidence. High, medium or low. SrvYard states how sure the explanation is.
  3. Most likely cause and How to fix it. A short reading of the end of the output with a list of steps. The card says it is written by an AI model from the end of the output, with secrets removed, and asks you to check it before acting on it. Treat it as a second opinion, not as an instruction.
  4. Redeploy. Runs the deployment again with the same settings, after a confirmation (Deploy again?).

Depending on the situation the card can look different: Explain this failure if none was written yet, Try again if writing it failed, a notice if your plan does not include it, or nothing at all if the feature is off. The output on the same page is always there.

4. The usual causes

What the output says Likely cause What to do
git fetch failed: Permission denied (publickey). The server cannot read the repository: the deploy key is missing or was removed, or the repository path is wrong. In the site's Settings, check the repository and the key or connection used (the Keys card says what the server uses). Add SrvYard's deploy key to the repository, or reconnect the git host. See Connect a repository and pick a branch.
composer install failed: Your lock file does not contain a compatible set of packages. composer.json or the lock file needs a different PHP version or extension than the site has. Switch the site to the right PHP version, or update the lock file with composer update locally and push. See Choose and switch PHP versions.
npm run build failed with exit code 137 (out of memory). The build ran out of memory and was killed. Give the server more memory or swap, or build elsewhere and deploy the assets. See Disk full, out of memory or a slow server.
php artisan migrate failed: Column already exists: Duplicate column name ... A migration ran partly before, or the schema was changed by hand. Fix the database state or the migration, then redeploy. Do not re-run a migration that has half-applied without looking at the table first.
The deploy script exited with status 1 A command in your script returned an error. The real message is a few lines up. See Write and test a deploy script.
A script that runs very long and stops The deploy script is stopped after 780 seconds. Move slow work (a big asset build, data imports) out of the script, or into a queued job.
The release is live, but the health check answered HTTP 500. The release switched, but the site answers with an error. Roll back first, then read the application log. See step 5.

The last row is special: the health check runs after the switch. The settings page has a card for it.

The Health checks card in the site settings
A health check marks a deployment failed when the new release answers badly.
  1. Check the site after each deployment. When on, SrvYard requests a URL after the release is live. Any answer from 200 to 399 passes.
  2. URL or path. A path such as /up, or a full URL on one of the site's own domains. Empty checks the home page.
  3. Save. A check that fails marks the deployment as failed but does not roll back, as the card says.

If your check keeps failing for a reason that is not a real outage, for example a path that needs a login, point it at a page that answers 200 without one.

5. When the release is live but broken

A deployment that failed its health check is already serving visitors. Handle it in this order:

  1. Restore service. On the deployment list, open the actions menu of the last Finished deployment and choose Roll back to this. A rollback switches the site back to that release without running the deploy script. It needs zero-downtime releases and a release that is still kept. See Zero-downtime releases and rollbacks.
  2. Find the cause in the application's log under Logs and in the deployment output.
  3. Fix it in a new commit or setting, then deploy again.

On a site without zero-downtime releases there is no previous release to go back to. Fix forward quickly, or restore from a backup.

Warning

A rollback does not undo database migrations. If the failed release changed the schema, check that the older code still works with it before you roll back.

Troubleshooting

  • The deployment stays on Queued. A deployment for the site is already running, or the server is busy or disconnected. Check the server's status. See Fix a server that will not connect.
  • It worked locally and fails on the server. The server has another PHP version, no Node.js or different memory. Compare the versions in the site settings with your machine.
  • The output is empty or stops after "Running the deploy script". The script produced nothing or hung. Add set -x to the top while you debug, or run the commands under Commands on the site.
  • A deployment is stuck as Running. Open the actions menu of its row and cancel it if the menu offers that. A run that is really stuck can also be reset through the API (POST /deployments/{deployment}/reset). Then deploy again.
  • I do not see a Why it failed card. Only failed deployments have one, and it depends on your plan and the organisation's settings.
  • Push to deploy did not start anything. The webhook at your git host may not be registered or may be pointed at the wrong branch. See Push to deploy with webhooks.
Last updated 2026-10-248 min readNeed help? Contact support
PreviousFix a server that will not connectNextFix a 502 Bad Gateway on your site