Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Operations and Alternatives

Troubleshooting Heroku Errors

A practical method for debugging a broken Heroku app: read logs, check dyno state, decode H and R error codes, roll back a release, use maintenance mode and run one-off dynos.

Something broke in production and users are waiting. This lesson gives you a calm routine to follow, a table of the error codes you will meet most often, and the commands that restore service quickly. The CLI cannot run on this site, so the commands are read-only; a code lookup and a triage stand-in are runnable.

The first five minutes

  1. Is the app up? heroku ps --app my-app shows each dyno as up, starting, crashed or idle.
  2. What do the logs say? heroku logs --tail --app my-app, and look at the lines just before the first error.
  3. What changed? heroku releases --app my-app lists every release (code deploy or config change) with who made it and when. Most outages start right after a release.
  4. Roll back if a release is to blame. heroku releases:rollback v42 --app my-app creates a new release from an earlier version and restores service in seconds. Rolling back does not undo database migrations; this is why migrations must be backward compatible.
  5. Check the dependencies: heroku pg:info, heroku addons, and the Heroku status page, in case the platform has an incident.
flowchart TD
    A["Users report errors"] --> B["heroku ps<br/>dynos up?"]
    B -->|"crashed"| C["heroku logs --tail<br/>find first error"]
    B -->|"up"| D["Check router codes<br/>H12 / H13"]
    C --> E{"Recent release?"}
    D --> E
    E -->|"yes"| F["releases:rollback"]
    E -->|"no"| G["Check database, add-ons,<br/>platform status"]

Check state, read logs, compare with recent changes, then roll back or dig deeper.

Error codes

Heroku prefixes platform errors with a letter and number. H codes come from the router (HTTP) and R codes from the runtime (dynos).

Code Name Typical cause and fix
H10 App crashed Process exited after a request or failed to boot. Read the stack trace above it.
H12 Request timeout A request took over 30 s. Speed it up or move work to a worker.
H13 Connection closed without response The dyno closed the socket (crash, restart, worker timeout).
H14 No web dynos running heroku ps:scale web=1 or add a web line to the Procfile.
H18 Server request interrupted The server stopped mid-response, often on restart or when the client left.
H20 App boot timeout Web dyno did not become ready in time.
R10 Boot timeout Process did not bind to $PORT within 60 s.
R12 Exit timeout Process ignored SIGTERM for 30 s; handle shutdown.
R14 Memory quota exceeded Swap in use; reduce workers or memory, or upgrade the dyno.
R15 Memory quota vastly exceeded The dyno was killed; find the leak.

The most frequent beginner error is R10 (boot timeout) or H14: the web server listens on a fixed port instead of $PORT, or the Procfile is wrong. A correct Procfile and server binding look like:

TEXT
web: gunicorn app:app --bind 0.0.0.0:$PORT
JavaScript
app.listen(process.env.PORT || 3000);

Build and release failures

If the deploy fails, the build log is printed at the end of git push heroku main. Common failures:

  • No buildpack detected. The root has no package.json, requirements.txt, Gemfile or similar. Check you pushed from the right folder.
  • Dependency failed to build. A pinned version needs a system library the stack lacks; pin another version or add a buildpack.
  • Slug too large. The slug limit is 500 MB; add a .slugignore file and remove big assets.
  • Release phase failed. The release: command (migrations) exited with an error, so no new release is created and the old one keeps running. Fix the command and push again.

Using a one-off dyno

Terminal
heroku run bash --app my-app
heroku run python manage.py shell --app my-app
heroku run:detached "python scripts/backfill.py" --app my-app

heroku run starts a new dyno with the same code and config, so you can poke at things, but it is a separate machine: changes to files there disappear, and it is not the dyno that crashed. For failing web dynos, use the logs. Be careful: a one-off dyno talks to the production database and counts against the connection limit.

Maintenance mode

Terminal
heroku maintenance:on --app my-app
heroku maintenance:off --app my-app

Maintenance mode makes the router return a static page (status 503) without touching your dynos. Use it during risky migrations or a database restore. A custom page URL can be set with heroku config:set MAINTENANCE_PAGE_URL=....

Triage helper

Python Stand-in: look up router and runtime codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first three lines are decoded and the last one is reported as ordinary traffic.

Python Stand-in: which release should we roll back to?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Errors jumped at v42, so the last good release is v41. Note that v41 and v43 are config changes: rolling back also reverts config vars to their older values, which can surprise you, so check heroku config afterwards.

After the fire

Write a short post-incident note: what happened, how it was noticed, how long it took, the fix, and one action to stop a repeat (a test, an alert, a safer migration). Many outages are caught earlier by the alerts described in logging.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A web dyno repeatedly shows R10. What is the usual cause?

    R10 means the process did not bind to the port Heroku assigned within 60 seconds.
  2. 2. What does heroku releases:rollback v42 do?

    It makes a new release based on v42; the database is not rewound.
  3. 3. What does H14 mean?

    H14 appears when no web dyno is running to receive the request.
  4. 4. Why is a one-off dyno not the place to debug a crashed web dyno?

    heroku run starts a fresh dyno with the same code and config; use logs to see what the web dyno did.

Summary

  • Triage in order: dyno state, logs, recent releases, dependencies and platform status.
  • Learn the main codes: H10, H12, H13, H14, R10, R14, R15.
  • Roll back with releases:rollback; migrations are not undone.
  • Use one-off dynos and maintenance mode carefully, and learn from each incident.

Next: Heroku Alternatives and Migration