Nested exceptions for all rubies
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


This simple library adds support for nested exceptions in Ruby.


It can be really painful to debug a situation where a library rescues an exception and throws a different one, or when it has a bug in its exception handling logic. This gem goes a diving catch and recovers the play!

The best way to learn more about this topic is to investigate the great source of information at the Exceptional Ruby site.

How do I use it?

The best way to use it is to simply add the following line of code to your project:

require 'nested_exceptions/global'

That includes the NestedExceptions module in all of Ruby's base exception classes (except the Exception root class), magically enabling you to debug the trickiest, buggiest libraries.

I'm not sure I want to include it globally

If you want to try it out without extending Ruby's exception classes, you can also do the following:

require 'nested_exceptions'

class MyException < StandardError
  include NestedExceptions

That will only extend your class and leave the rest of the exception classes untouched.

Does it change anything?

Yes. A bit of extra information is added to your backtraces. In addition to the standard backtrace, you'll get a little bit of nesting information.

ruby examples/example.rb original

examples/example.rb:32:in `rescue in double_bug': oops (RuntimeError)
  from examples/example.rb:30:in `double_bug'
  from examples/example.rb:42:in `<main>'

ruby examples/example.rb nested

examples/example.rb:30:in `rescue in double_bug': oops (RuntimeError)
  from --- cause: ErrorSpec::InternalError: problem
  from examples/example.rb:20:in `rescue in problem'
  from --- cause: RuntimeError: bug
  from examples/example.rb:10:in `bug'
  from examples/example.rb:14:in `nested_bug'
  from examples/example.rb:18:in `problem'
  from examples/example.rb:24:in `nested_problem'
  from examples/example.rb:28:in `double_bug'
  from examples/example.rb:35:in `<main>'

It also adds two methods to the exception:

  • #root_cause: allows you to easily get the first exception
  • #cause: get the exception (if any) that may have caused this one


Do not include the NestedExceptions module in a subclass before adding it to its superclass. That will cause the nested exceptions feature to deactivate itself to prevent a stack overflow.