Jan 20, 2017
š Custom (400 / 500) Error Pages in Ruby on Rails ā Exception Handler
Custom Rails error pages can be set up relatively simply. This tutorial explains the 3 methods to do it (config.exceptions_app)ā¦
š Overview
Publishing a Rails application is a major investment and weād all love our
apps to be used & enjoyed by as many as possibleā¦
Unfortunately, an impediment to this are Railsā default error pages ā“
Railsā default error pages are boring and bland. More importantly, theyāre unprofessional and may dissuade users from further engaging with the app.
Hitting an error, youād expect the following:
These show regardless of framework and technology stack.
The important thing to note is that they are NOT errors in themselves. They are HTML pages which describe the results of erroneous HTTP requests.
Big difference.
Any time you receive data from a web service, itās done via HTTP. HTTP is TCP/IP on port 80 and is the core of all web sites/apps:
What you see after ANY HTTP request is the body of the HTTP response (pictured above). Even if an erroneous status code is returned, the client/browser will display the HTML payload.
For us, it means that it does not matter HOW that HTML is generated (static or dynamic). All that matters is that itās present and has the necessary infoā¦
As such, if weāre able to utilize the Rails views/controller stack, we should
be able to create branded error pages which retain your appās layout.
Fortunately, Rails has a hook just for this called exceptions_app.
This hook is present in the Rails core, and can be changed in one of the environment files (./config/application.rb). It is the key to creating
custom error pages in Rails.
It is used by Rails to create valid HTML for an erroneous HTTP
request (more explained below). ā“
By default, it pulls the error HTML files that Rails has in its public directory.
The key to changing your error pages in Rails is to ensure this hook has a callback which delivers HTML code from your views/layouts. This can be done with 2 methods: self.routes / Controller.action(:x).call(env):
Our gem does this automatically.
Downloaded 94,000+ times, itās currently the most popular custom Rails 400/404/500 error pages solution for Rails:
In this tutorial, weāll showcase the gem and explain how to manually
set up custom error pages on Railsā¦
āļø How It Works
Default Rails 400/500 error pages are a set of HTML files stored in
the public directory of your application:
These files are a fail-safe, loaded whenever your application raises an
error. The reason why theyāre vanilla HTML (rather than Rails views) is to prevent further issues being incurred by calling them.
As you can see, one of the reasons why theyāre so bland is because they contain their CSS directly in the file ā“
Since the files are hard-coded, most people take it as a sign that Rails cannot serve exceptions [dynamically] from its controller/view stack.
The good news is that YES, you can create custom error pages in Rails. You
can use the same CSS, layouts and controllers that you have alreadyā¦
To understand how to do this, you need to appreciate how it works. It
comes down to something called the middleware stackā¦
Middleware is a term used to describe a series of scripts used to interface different types of application. For example, apps built for Linux may use middleware to communicate with Windows based apps over a network.
Rails is built on top of Rack ā a middleware suite for Ruby which translates HTTP requests into Ruby/Rails transactions. The Rack middleware stack works on all levels to provide a range of functionality for Rails applications:
One of Rackās middleware scripts is ActionDispatch::ShowExceptions ā loaded each time your application raises an exception.
Because Rails is not HTTP, this script is responsible not only for catching exceptions, but also translating them into an HTTP-compatible response:
It is important to note that the middleware, whilst important, is
almost never seen and generally not changed.
Since the middleware acts on the lowest level of Rails applications
(interfacing with HTTP requests), itās rare you should get involved with it.
You can see Railsā middleware setup here ā“
ActionDispatch::ShowExceptions is present half way through the stack.
The key is that when considering how to change Rails custom error pages, youāre not changing anything in Rack/Rails itself.
Youāre adding your own HTML generation to the exceptions_app hook. Hooks work by relying on a sub-function to provide a return value, which is then used in the main function (similarly to a variable)ā¦
By default, exceptions_app invokes ActionDispatch::PublicExceptions which uses the path_info attribute of the erroneous request to load one of the default HTML files:
This means that if you are able to use your own custom callback in place of ActionDispatch::PublicExceptions, youāll be able to provide your own HTML responses.
To do this, you need to define a callback and populate config.exceptions_app in ./config/application.rb with itā¦
There are two types of callback you can use:
ā self.routes (routes)
ā YourController.action(:x).call(env) (custom controller)
If you use the routes, Rails will infer the path_info from the
erroneous request, accessing the route as if the request was directed thereā¦
If you use a controller, the action is loaded directly and as such, you only need to consider how youāre going to deliver an appropriate view & layout.
Hereās howā¦
ā Overview
There are 3 ways (2 methods) to create custom Rails error pages:
- š Routes (simplest)
- š“ Custom Controller (most extensible)
- ā”ļø Gem (automates custom controller method)
ā Routes is simplest. Youāre able to push the exceptions_app callback directly to self.routes ā the routes will infer the path_info and route to the status code of the error. You then catch the request when it hits the routes.
ā Custom controller builds on top of this to deliver an ActionController response to exceptions (allows you to use your own views/layouts).
ā Gems automate the custom controller method. They create a custom controller and keep it in a Rails engine. This allows the gem to store models/views etc without polluting the main appā¦
ā”ļø Gem (Exception Handler)
ExceptionHandler was designed in 2014 and quickly gained traction due to its simplicity. The gem is a one-click solution for custom Rails error pagesā¦
ExceptionHandler has been downloaded over 94,000 times and is one
of the most widely used, supported & simplest way to create Rails error pages.
With its zero configuration setup, the gem provides anyone with professional error pages for Rails ā fully compatible on Rails 4 & 5 ā¦
As the gem has been downloaded 94,000+ times, itās considered
one of the more popular for Rails.
After installation, it automatically overrides the config.exceptions_apphook and sends any exceptions to our custom controller:
The custom controller is designed to show either your appās default layout
(40x errors) or our custom exception layout (50x errors).
There is absolutely ZERO work required to set up the gem, making it a favorite of some of the most active Rails developers in the worldā¦
The core functionality of the gem is to change the layout when an error is raised. Unlike using a routes-based method, it gives total control of the flow.
ExceptionHandler is able to serve the same data but in different formats, showcasing 50x errors on a custom exception layout & 40x errors in your own branded view.
The trick is ensuring that 50x errors do NOT call the DB or invoke variables. 40x errors are ONLY for Not Found errors; 50x errors are from the server.
ExceptionHandler is able to provide professionally branded Rails error pages to the following specsā¦
- āļøWorks fully on Heroku
- āļø 100% Rails 4 & 5 compatible
- āļø Adds professional exception pages to your Rails applications
- āļø Works in production, staging and development
You can download it here:
š¦ HTTP Status Codes
Before explaining the manual methods, we need to explain
HTTP Status codes and their role in the Rails exception process ā
HTTP status codes are EXTREMELY important when considering Railsā
error responses. Not in their own capacity but due to how they work with HTTP as a wholeā¦
Because the ENTIRE web is based on HTTP, each time you receive an HTTP response, it needs to respond with one of the following status codes ā
Since Ruby is not native to HTTP, Rails has to translate exceptions into
valid HTTP responses. This is why its middleware takes so much pain to associate the exception to an HTTP status code.
The importance of this is that although generating a valid HTTP status code is necessary for getting Rails to work online, it does not define the type of content sent back to the client.
In other words, just because Rails experienced an exception, doesnāt mean that it needs to send back vanilla HTML pages to the client. You can set it up to respond with views/layouts that you already have set upā¦
The trick is understanding the types of error, and what they mean for handling error responses.
There are 5 types of HTTP status code, 2 of which are erroneous:
- ā 1xx Informational (no error)
- ā 2xx Success (no error)
- ā 3xx Redirection (no error)
- š 4xx Client Error (resource missing error)
- š 5xx Server Error (internal server error)
EVERY time you receive a response from HTTP, a status code is includedā¦
HTTP only has two error types.
These are the only erroneous status codes that Rails is able to send back to
the HTTP client. It doesnāt matter if your application starts WW3, the only thing that matters to HTTP is a valid erroneous status code was returnedā¦
This means that when considering how to handle Rails errors, youāre really looking at ways to manage the 40x and 50x errors produced by your app:
40xerrors mean that content was not found.50xerrors mean that the server had an error.
Neither of these status codes have any bearing on how your application should behave (explained in a second).
What they do mean is that you only need to consider 2 types of response. And in both cases, HTTP still permits the sending of a message body:
As such, weāre still able to send back HTML in either case.
The difference lies in how weāre able to do it.
Railsā default is to load the default HTML files. We want to change this to use our own views/CSS. To do it, all we need to set up a custom controller action and hook it into exceptions_appā¦
š£ Exceptions
To better understand, itās important to consider the way in which
Rails translates Ruby/Rails exceptions into HTTP-valid errors.
Specifically, each time an exception is raised, it will have a class associated with it. Ruby is an object oriented language, and binds every action to a class.
Rails cannot accommodate for every class raising an exception. Instead, it
takes the most common and associated them to specific HTTP errors
(from Rack::Utils::HTTP_STATUS_CODES)ā¦
You can extend this list by using the following code:
# config/application.rb
config.action_dispatch.rescue_responses.merge!(
"YourCustomErrorClass" => :not_found
)Any class that isnāt matched defaults to the 500 Internal Server Error:
Again, this doesnāt matter to Rails.
Itās ONLY for HTTPā¦
It means that if youāre handling exceptions with a custom implementation, you only need to be concerned with how Rails is handling the generation of the returned HTML.
All the HTTP stuff is taken care of prior to the callbackā¦
The key is to develop a system which takes requests through exceptions_app and forms HTML that works for both types of HTTP error (40x & 50x).
The main difficulty lies in 50x error pages.
Since 50x errors show when Rails encounters an application error, you cannot use the standard view/CSS flow to generate HTML. You need to use a custom layout & ensure that youāre not calling the database at allā¦
Hereās howā¦
āļø Manual Implementations
Manually changing the exception handling process simply means putting your own callback into the exceptions_app hook.
How you do this determines what gets shown on screen..
š Routes
A routes based implementation uses self.routes as the callback.
This takes the path_info attribute of the erroneous request object and opens a route from it. This is how most people set up custom error pages.
Unfortunately, due to the fact that the exception request is not passed to the routes, youāre very limited in scope as to what youāre able to do with respects to data, etcā¦
# config/application.rb
config.exceptions_app = self.routes# config/routes.rb
%w( 404 422 500 ).each do |code|
get code, controller: :application, action: :error, code: code
end# app/controllers/application_controller.rb
def error
render status_code.to_s, status: (params[:code] || 500)
end# app/views/application/404.html.erb
# stuff here
š“ Controller
A custom controller implementation is much simpler.
Instead of sending exceptions to the routes, you invoke a controller action directly. The key is sending the erroneous environment, which can only be done as exceptions_app is a callback.
The important thing to appreciate with a controller is that it requires setting up the views a 500 error layout and
# config/application.rb
config.exceptions_app = ->(env) { ExceptionsController.action(:show).call(env)}# app/controllers/exceptions_controller.rb
def show
# Specific code
end# app/views/exceptions/show.html.erb
@exception.description
ā”ļø Gem
Obviously, our recommendation is to use the gemā¦
If you are intent on using a custom solution, you should definitely look to create a custom controller.
This way, you retain full control over the layout/view process. Not only this, but itās much more concise & extensible (you can create a model to record exceptions in the database if you wanted).
šThanks for reading
Please feel free to ask for help below if required.
ā References
Several good references if you need further info:
- http://blog.siami.fr/diving-in-rails-exceptions-handling
- https://stackoverflow.com/questions/19103759/rails-4-custom-error-pages-for-404-500-and-where-is-the-default-500-error-mess/19279062#19279062
- https://mattbrictson.com/dynamic-rails-error-pages
- https://makandracards.com/makandra/41790-how-rails-chooses-error-pages-404-500-for-exceptions
ā
