Tips & tricks
Debug a failed deploy: a 6-step checklist
When a deploy fails, check in this order: build, pre_deploy, port, environment, dependencies and memory. Most problems are one of these six.
· 2 min read
In short
- Read the deploy log first, then work from build to runtime
- The usual suspects: wrong port, missing variable, failing pre_deploy, out of memory
- A failed deploy keeps the previous version running, so there is no panic
A red deploy feels urgent, but it is usually boring: one of six causes. Work through them in order, because each step rules out the one before it.
1. Did the build fail?
Open the deploy log. Typical causes: a missing file because of .dockerignore, a wrong build: path, or a lockfile out of sync. See smaller, faster Dockerfiles.
2. Did pre_deploy fail?
A failing migration stops the release by design, and the output is in the log. It also fails if it runs longer than five minutes. See migrations on every deploy.
3. Does the port match?
The port: in prongo.yaml must be the port your app actually listens on. An app on 3000 with port: 8080 starts fine and never becomes healthy.
4. Is every variable set?
A missing secret is the most common runtime crash. Check that each name your code reads exists in the dashboard, with the exact same spelling. Details in sharing variables between services.
5. Are dependencies declared?
If the app crashes on first start but works on retry, it probably started before its database. Add depends_on.
6. Did it run out of memory?
A service killed shortly after start often hit its memory limit. See fitting a service into its limits.
Frequently asked questions
Does a failed deploy take my site down?
No. With zero-downtime rollouts the previous version keeps serving until the new one is healthy, and a failing pre_deploy command stops the release.
Where do I find the error?
In the deploy log in the dashboard. It includes build output and pre_deploy output.