Heroku Error Pages Gem

Apr 20, 2025

I wrote a gem - heroku_error_pages - for Rails applications running on Heroku that allows you to build custom error pages and automatically host the pages in S3. This allows you to easily build custom error pages for Heroku - and keep them up to date as part of the release process as your application styles change.

The idea behind this gem started two years ago when I was working on a Rails application - deployed on Heroku - where I wanted to use the Heroku feature to enable custom error pages. It felt like something that should be completely straightforward to enable since:

  1. I’m using Rails to develop and serve custom HTML content
  2. Heroku already knows how to run my Rails application

Of course it’s not that simple since these pages need to be accessible even when your application is unavailable, which is why Heroku recommends using Amazon S3. I ended up attempting to build a quick custom error page in Rails and exporting a static version of this page to S3 - which means you quickly run into the question of how to export all the necessary assets, making sure these are referenced correctly, copying these to S3 and ensuring they are in the correct relative paths. For example, if the custom error page references /app/public/assets/application-{FINGERPRINT}.css you need to ensure that this relative path is being maintained within S3.

This entire task felt much more difficult than anticipated, since most of these steps are already being done by Rails and Heroku as part of deployments (or at least felt very similar to the asset sync process from Rails 4). Once I had everything working this still left me with the problem that the application styles are going to change but the custom error pages would not. I then attempted to write a basic rake task that would

  1. Render the error template
  2. Copy the HTML to S3
  3. Copy all the assets to S3 (in the correct relative locations)

This gave me a scripted way to update the error pages, but they still wouldn’t be updated automatically - which is why I attempted to run this task as part of the Heroku Release Phase. This gem is the result of extracting that work into a reusable gem.

It automates this process:

  1. Use ActionController::Base.render to render the error and/or maintenance pages maintained in Rails. This allows you to render the template outside of the context of a web request.
  2. Export the rendered HTML and all assets to S3 while maintaining all the relative paths. This is done by setting the asset_host on the controller to nil and iterating through all assets in Rails.public_path.
  3. Invoking this entire process as part of the Heroku Release Phase.

At the time of writing the gem is available for use but AFAIK I am the only one using it (which isn’t bad, since I wrote it partially for myself). I added a quick Heroku test application to make sure it’s working and with the help of ChatGPT put together this nice error page. (The AI is truly amazing at quickly putting together prototypes)

Custom Maintenance Page

If you’re interested in using this gem I would love to get some feedback, either here or as an issue on the github repo.