When a deployment fails: what to fix, retries and automatic retries
Most failures fix themselves: the Recovery Agent repairs what it can during the run (see Launching & reading the logs). When a deployment still fails, The Deployer tells you what went wrong, who has to fix it, and whether running it again is worth it. This page explains that screen, running a deployment again, and automatic retries.
What to do: who fixes it
Open the failed deployment. The steps panel shows a card that sorts the failure into one of these kinds. On a phone, tap What to do to open it.
| Kind | What it means | Who fixes it |
|---|---|---|
| Your app couldn't be built from the repository | Your code couldn't be built or started, for example a missing module or a build error. The card names the files to look at and the branch. | You, in your repository. Push the fix, then run it again. |
| Your cloud account blocked this step | Your cloud provider refused the request: usually a quota, a service that isn't turned on yet, or a permission the connected credentials don't have. | You, in your cloud provider's console. Running it again first hits the same wall. |
| Credentials rejected | Your cloud or git provider rejected a stored key. | You, by replacing the key (see below). |
| Your repository's branch protection stopped the push, or your git connection cannot write | Your git host turned away a push. | You, in your repository's settings or by reconnecting with a token that can write. |
| A step didn't complete | It stopped while talking to your servers or your cloud, not because of your code. | Often nobody. It's usually worth one more run. |
Some build stops have their own cards, such as a missing build secret or a package repository that refused the build. Each card says what to change and where.
Click Show the error from the log to see the lines that matter. Click Ask why it failed for a plain-language breakdown in Chat.
If The Deployer's agents have since learned a fix for this exact failure, the card says Our agents learned from this failure, and running it again applies what they learned.
Running it again
The button at the bottom of the card names what it runs, for example Run pull & restart again or Run capacity change again. A deployment always runs again as the same kind it was. A failed Pull & Restart runs as a Pull & Restart, never as a full re-provision of your servers. For targeted runs the top of the steps panel also has Run again. A full deployment has Deploy again.
The plan is made fresh each time, so a fix you pushed since is what gets built. Running it again counts as a deployment toward your plan's daily limit, except a start or stop of servers.
Automatic retries
A failed deployment can be tried again on its own. Set how many times in the Automatic retries card on your project's Dashboard:
- Under Retries after a failed deployment, pick Off or a number from 1 to 5. The default is 2.
- Click Save.
The Deployer waits 1 minute before the first retry, 2 minutes before the second, and 4 minutes before each one after that. Each attempt starts from your branch as it is then, and the agent sees what earlier attempts failed on and tried, so it tries something different.
While a retry is waiting, the failed deployment shows Trying again automatically in with a countdown and the attempt number, such as attempt 2 of 3. After the last attempt it says Stopped after that many attempts.
Automatic retries apply only to full deployments, Pull & Restart and environment updates. A resize, a start or stop, a domain change or an add-on change is something you chose, so it is never re-run unasked. Retries also stop early when only you can fix the problem, such as a rejected credential, a cloud quota or a refused push, and while the project's servers are stopped.
Retries never loop. A commit that has used up its attempts isn't deployed again on its own. A fix the agent pushes is deployed as one of these attempts, not as a new push. A new push from you starts fresh, and so does a deployment you start yourself. Each attempt counts as a deployment toward your plan's daily limit.
Changing the setting needs the Retries and health checks permission.
Cancelling a waiting retry
Click Cancel automatic retry under the countdown. Nothing else changes, and you can still run the deployment again by hand. Clicking Run again yourself also calls off the waiting retry. Lowering the limit stops a waiting retry that is now past it.
When credentials are rejected
If a provider rejects a stored key (for example an expired GitHub token or a rotated cloud key), the card says Cloud credentials rejected or names your git host. Click Replace credentials (or Replace token), confirm with your account password, and paste the new key. The Deployer checks the new key before it replaces the old one. If it fails, your current key stays in place. The connection keeps its projects, so nothing else needs changing. When the key is replaced, click Redeploy now.
See Viewing & replacing your credentials.
Leftover DNS records
A failed deployment can leave DNS records behind. They don't block you. When you set up a domain again, The Deployer shows them as Leftover records from a previous deployment. They aren't used by any other project, so you can click Remove leftover records & continue. A record that another of your projects uses is shown under In use by another project and is never removed from here. Remove it from that project first, or choose a different subdomain.
An AI coding agent connected through The Deployer's MCP server can read the same explanation, fix the cause and run the deployment again for you: see Use The Deployer from your AI coding tool.
Common problems
- The same failure every time. Read who fixes it on the card. If it's your repository or your cloud account, running it again won't help until that changes.
- No retry happened. Automatic retries may be Off, the limit may be used up, a newer deployment may have started, or the failure is one only you can fix.
- "The daily deployment limit has been reached." Wait until tomorrow, or move to a plan with a higher limit.
- "This deployment is still in progress." Wait for it to finish, or cancel it first.