Error Pages
Last updated December 03, 2024
Table of Contents
Heroku’s HTTP router serves unstyled HTML with HTTP status code 503 (Service Unavailable) when your app encounters a system-level error, or while maintenance mode is enabled.
Other errors, such as application errors (a 404 or 500), will display your application’s error page and not the Heroku error page. Only system-level errors that result in no response, or a malformed one, will display the Heroku error page discussed here.
Debugging
Logs are the first place to look when your users report seeing the Heroku error pages. Use the heroku logs
command to view the unified event stream for your application and the state of the Heroku platform components supporting your application.
$ heroku logs
2011-03-01T16:16:29-08:00 heroku[web.1]: State changed from starting to crashed
2011-03-01T16:16:59-08:00 heroku[router]: at=error code=H10 desc="App crashed" method=GET path=/ host=example-app-1234567890ab.herokuapp.com fwd=17.17.17.17 dyno= connect= service= status=503 bytes=
In this example, the router tried to serve a page for the app, but the web process is crashed. The Error H10
log entry contains the error code H10
that identifies the cause of this particular issue. Refer to the full list of error codes to determine the cause of the error you’re seeing.
To learn more about tracking down errors that may lead to the error pages being generated, visit the article on Logging. If you need to debug further, learn how to SSH into a dyno.
Customize pages
Custom error pages are currently unavailable for Fir-generation apps. Subscribe to our changelog to stay informed on when we add this features to Fir.
The pages displayed to your users when the application encounters a system error or is placed in the maintenance state can be customized. Customizing these pages allows you to present a more consistent UI to your users.
Create and store the custom pages
Create your custom pages as static HTML. You may wish to use the default HTML served by Heroku as a template:
- https://www.herokucdn.com/error-pages/application-error.html
- https://www.herokucdn.com/error-pages/no-such-app.html
- https://www.herokucdn.com/error-pages/maintenance-mode.html
- https://www.herokucdn.com/error-pages/ssl-cert-error.html
You can reference images or CSS from the HTML as long as you use relative paths (for example, <img src="error.png">
) and you upload the other assets into the same place as the HTML.
You can host the pages anywhere that can serve web pages. We recommend uploading to Amazon S3. If you use S3, don’t forget to set the HTML and all assets to be publicly readable.
Due to security settings in the IFrame, links on your custom error page may not work unless you specify “target=_blank” in the HTML.
Configure your application
Set the ERROR_PAGE_URL
and MAINTENANCE_PAGE_URL
config vars to the publicly accessible URLs of your custom pages:
$ heroku config:set \
ERROR_PAGE_URL=//s3.amazonaws.com/<your_bucket>/your_error_page.html \
MAINTENANCE_PAGE_URL=//s3.amazonaws.com/<your_bucket>/your_maintenance_page.html
Testing
To test your maintenance page, type:
$ heroku maintenance:on
$ heroku open
The custom page will be served and your application logs will show an H80 code for that web hit indicating that a maintenance page was served to the user.
$ heroku logs -p router -n 1
2010-10-08T17:44:18-07:00 heroku[router]: at=info code=H80 desc="Maintenance mode" method=GET path=/ host=example-app-1234567890ab.herokuapp.com fwd=17.17.17.17 dyno= connect= service= status=503 bytes=
To test your error page, you can push a bad deploy such as putting a syntax error into a key configuration file, or by creating a path on your app that sleeps for 35 seconds (thereby triggering the error H12 Request Timeout. Visit an app or path with such an error, while watching the logs:
$ heroku logs --tail
2010-10-08T18:04:40-07:00 app[web.1]: Sleeping 35 seconds before I serve this page
2010-10-08T18:05:10-07:00 heroku[router]: at=error code=H12 desc="Request timeout" method=GET path=/ host=example-app-1234567890ab.herokuapp.com fwd=17.17.17.17 dyno=web.1 connect=6ms service=30001ms status=503 bytes=0
2010-10-08T18:05:15-07:00 app[web.1]: Done sleeping
The custom error page will be displayed in your browser.
SSL
If your site is accessed via SSL, some browsers will display a warning or error if the maintenance and error pages do not also use an HTTPS URL. Be sure to use matching application and error page protocols.