📣 This post originally appeared as Custom Exception Handling in Ruby on The Bearer Blog.
In Ruby, like in most languages, an exception is a way to convey that something went wrong. While some languages only use exceptions for truly exceptional circumstances, like run-time errors, Ruby uses exceptions for a wide variety of errors and unexpected results.
In this article, we will look at:
- How to handle common errors
- How to react to a specific exception
- How to create your own custom exceptions
How to raise and rescue exceptions in Ruby
Your own functions, Ruby, or gems and frameworks can raise exceptions internally. If you are familiar with Javascript of a C-inspired language, you may know of the try/catch concept. Ruby has something similar for handling exceptions, using the begin-end block. It can contain one or more rescue clauses. Let's look at an example:
begin
# Your code
cause_an_error()
rescue
puts "An error has occurred"
end
This is one way to build a basic ruby exception handler. This is also a way to catch common errors, as rescue without any arguments will catch any StandardError and its subclasses.
You can also assign the exception to a local variable, using rescue => var_name, to gain access to properties of the exception. For example:
# ...
rescue => error
puts "#{error.class}: #{error.message}"
end
We said that rescue on its own catches StandardError and its subclasses. You can also specify the error type you'd like to target. This allows you to use multiple rescue clauses. For example:
begin
# do something that raises an exception
do_something()
rescue NameError
puts "A NameError occurred. Did you forget to define a variable?"
rescue CustomError => error
puts "A #{error.class} occurred: #{error.message}"
end
In this example, the multiple rescue blocks handle each error type separately.
You can also rescue multiple error types at the same time by separating them with a comma. For example:
# ...
rescue NameError, CustomError, ArgumentError => error
# handle errors
end
In these examples, we use begin and end. You can also use rescue inside a method or block without the need for begin and end. For example:
def my_function
perform_action()
rescue => error
puts error.message
end
Else and ensure
In addition to begin-end and rescue, Ruby offers else and ensure. Let's look at an example:
begin
# perform some actions
rescue => error
puts "Handle the #{error.class}"
else
# Code in the else block will run if no exception occurs
do_someting_else()
ensure
# Code in the ensure block will always run
always_do_this()
end
Any code in the else block will run if no exceptions occur. This is like a "success" block. Code in the ensure block will run every time, even if the code does not throw an exception.
To summarize:
- The code in
beginwill try to run. - If an error occurs and throws an exception,
rescuewill handle the specified error types. - If no error occurs, the
elseblock will run. - Finally,
ensure's block will run always.
Raising specific exceptions
Now that we know how to handle, or rescue, errors and exceptions we can look at how to raise or throw an exception. Every exception your code rescues was raised at some location in the stack.
To raise a StandardError:
raise StandardError.new('Message')
# OR
raise "Message"
Since StandardError is the default exception type for raise, you can omit creating a new instance and instead pass the message on its own.
Let's look at this in the context of a function and a begin-end block.
def isTrue(x)
if x
puts "It's true"
else
raise StandardError.new("Not a truthy value")
end
end
begin
isTrue(false)
rescue => error
puts error.message
end
Here we have an isTrue function that takes an argument (x) and either puts if x is true or raises an error if it is false. Then, in the begin block rescue ensures that the code recovers from the raise within isTrue. This is how you will commonly interact with errors. By recovering from a raise that occurred in another part of your codebase.
Creating custom exceptions
If you are building a gem or library, it can be useful to customize the types of errors your code raises. This allows consumers of your code to rescue based on the error type, just as we've done in the examples so far. To create your own exceptions, it is common to make them subclasses of StandardError.
class MyCustomError < StandardError; end
Now, you can raise MyCustomError when necessary, and your code's consumers can rescue MyCustomError.
You can also add properties to custom exception types just as you would any other class. Let's look at an example of a set of errors for a circuit breaker. The circuit breaker pattern is useful for adding resiliency to API calls. For our purposes, all you need to know is that there are three states. Two of them may cause an error.
Let's create a custom error that, instead of just taking an error message, also takes the state of our circuit.
class CircuitError < StandardError
def initialize(message, state)
super(message)
@state = state
end
attr_reader :state
end
The new CircuitError class inherits from StandardError, it passes message to the parent class and makes state accessible to the outside.
Now, if we look at this in the context of a rescue, we can see how it might be used.
begin
raise CircuitError.new("The circuit breaker is active", "OPEN")
rescue CircuitError => error
puts "#{error.class}: #{error.message}. The STATE is: #{error.state}."
# => CircuitError: The circuit breaker is active. The STATE is: OPEN.
end
The rescue block can now take advantage of the added state property that exists on the error instance.
Adding custom exceptions to your modules
If you are developing a module, you can also take this a step further by incorporating custom error types into the module. This allows for better name-spacing and makes it easier to identify where the error is coming from. For example:
module MyCircuit
# ...
module Errors
class CircuitError < StandardError; end
end
# ...
end
You can raise the error type as follows:
raise MyCircuit::Errors::CircuitError.new('Custom error message')
It is common for libraries to include a set of subclassed error types. Generally, these live in exceptions.rb or errors.rb file within the library.
Rescue exceptions based on the parent class
So far we've seen how to rescue exceptions, raise exceptions, even create our own. One more trick is the ability to recover from errors based on their parent class.
Let us take our circuit breaker error from earlier and split it into one parent and two children. Rather than require the raise clauses to pass in arguments, we will handle that in the errors themselves.
class CircuitError < StandardError
def initialize(message)
super(message)
end
end
class CircuitOPEN < CircuitError
def initialize
super('The Circuit Breaker is OPEN')
end
end
class CircuitHALF < CircuitBreaker
def initialize
super('The Circuit Breaker is HALF-OPEN')
end
end
Here, both CircuitOPEN and CircuitHALF are subclasses of CircuitError. This may not seem useful, but it allows us to check for either error individually, or all subclasses of CircuitError. Let's see what that looks like.
To rescue them individually would look like:
begin
# ...
raise CircuitOPEN
rescue CircuitHALF
# do something on HALF error
rescue CircuitOPEN
# do something on OPEN error
end
We could also group them together:
rescue CircuitHALF, CircuitOPEN
# do something on both
But even better, since they are both subclasses of CircuitError, we can rescue them all by rescuing CircuitError.
begin
raise CircuitHALF
# or raise CircuitOPEN
rescue CircuitError
# will catch both HALF or OPEN
end
By utilizing this method, your code can react to types of errors in addition to specific errors.
How to manage errors
This approach to handling exceptions in ruby goes a long way toward providing valuable errors to consumers of your code. Not only can you throw and raise exceptions, but your users can now catch exceptions in their ruby code that may come from your library.
At Bearer, we use an approach similar to this in our Agent codebase to provide our users with error details that help them identify where the problem is coming from.
If you're interested in preventing errors in your codebase, check out what we're building at Bearer. The Bearer Agent makes handling API inconsistencies easier by offering automatic remediations, resiliency patterns, and notifications with no changes to your code.
Explore more on the Bearer Blog and connect with us @BearerSH.
Top comments (0)