A New Approach to Errors

When your app is crashed, out of resources, or misbehaving in some other way, Heroku serves error pages to describe the problem. We also have a single page for platform errors, once known as the ouchie guy (pictured right).

While the approach of showing error information directly via the web has worked well enough, there was room for improvement on both developer visibility and professionalism of presentation to end users. With that in mind, we’ve reworked our approach on error handling, making improvements that should make it much easier for you, the developer, to diagnose and correct errors in your app.

This new approach can be broken down into four features:

1. Consolidated error page
2. Logging of error codes
3. Custom Error Pages add-on
4. Improved maintenance mode

These items are now available in public beta, activated by installing the Custom Error Pages add-on. Once the public beta period is over, items 1, 2, and 4 will become the default for all apps.

Let’s take a tour of this new world of error handling.

Consolidated Error Page

An error being served in a high-traffic app is more likely to be served to an end user than to the application developer; so showing information like “backlog too deep” or “request timed out” is useless and potentially confusing to the viewer. All error pages served over HTTP are now represented by a consolidated error page, and always serve with an HTTP status code of 503.

Logging of Error Codes

Because we’re no longer putting details of the error into the page served via HTTP, you’ll need to get at them some other way. In this new model, error details are now part of your application’s log. We’ve assigned a unique code to each type of error, and they’l be placed alongside the log line produced by the HTTP router. Like this:

18:05:10 heroku[router]: Error H12 (Request timeout) -> GET myapp.heroku.com/errortest dyno=web.1 queue=0 wait=0ms service=30000ms bytes=0

In this example, the dyno spent too long servicing the request and was timed out by the router. Each type of error gets its own error code, with all HTTP errors starting with the letter H. Here’s the complete list of error codes. In the future we’ll be adding codes for other kinds of errors that can occur (for example, errors during deployment).

Note that you’ll need the new logging add-on in order to see error code logging.

Custom Error Pages

The standard error page is unbranded, but you might wish to use an error page styled to match the rest of your site. You can’t do this directly, because these error pages are generated from outside your app. (When your app is broken or overloaded, it’s impossible for it to serve any page.)

The Custom Error Pages add-on gives you the ability to specify a URL to your own error page, which can have any text and style you want. Usage is simple:

$ heroku addons:add custom_error_pages
 Adding custom_error_pages to myapp...done.
 $ heroku config:add ERROR_PAGE_URL=http://s3.amazonaws.com/your_bucket/your_error_page.html

You can put your HTML anywhere, though we recommend S3 for its simplicity and reliability.

Improved Maintenance Mode

The final piece of the puzzle is a new maintenance mode, to address problems with our current maintenance mode implementation for apps with more than fifty dynos. This new implementation handles maintenance mode at the HTTP router, providing an instantaneous response for turning maintenance mode on or off regardless of the size of your app. It uses a standard page which serves with an HTTP 503 code. You can use the Custom Error Pages add-on to provide your own maintenance page to the router. (If for some reason you prefer the current maintenance mode, it’s available as Rack middleware.)

Conclusion

During the beta, adding the Custom Error Pages add-on will turn on the consolidated error page, logging of error codes, and the new maintenance mode. When the beta is over, everything other than the add-on itself will become standard for all apps. Custom Error Pages will become a premium-priced feature after the beta, reflecting its nature as useful primarily to production apps with significant investment in their brand image.

We believe these changes will significantly improve the experience of dealing with errors on Heroku. Give it a try and tell us if you agree!