Automatically retry a code block when an exception occurs
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 161 commits ahead, 27 commits behind songkick:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Automatically retry a code block when an exception occurs.

Build Status Dependency Status

require "retryable"
include Retryable

retryable(:tries => 3, :on => IOError) do

This calls read_flaky_sector and returns the result. If an IOError was raised, it tries the call again, and one more time (for 3 tries total) before giving up and letting the most recent exception propagate upward.


  • Bundler: gem "retryable", :git => "git://"

You must include the module before using it. This allows unrelated libraries to set up their own defaults without any chance of conflicts.

class MyUtility
  include Retryable
  retryable_options :tries => 10


Retryable uses these defaults:

  • :tries => 2 # try the call once, then retry once
  • :on => StandardError
  • :sleep => 1
  • :matching => /.*/
  • :detect_nesting => false
  • :logger => lambda { |task,retries,error| ... } # only logs if you specify a :task
  • :task => nil

You can pass custom settings every time you call the retryable command, or call retryable_options to change the default settings:

retryable_options :tries => 5, :sleep => 20
retryable { catch_dog }


By default Retryable waits for one second between retries. You can change this, even providing your own exponential backoff scheme.

retryable(:sleep => 0) { }                    # no pause between retries
retryable(:sleep => 10) { }                   # sleep ten seconds between retries
retryable(:sleep => lambda { |n| 4**n }) { }  # sleep 1, 4, 16, etc. each try
retryable(:sleep => nil) { }                  # don't even call sleep


If you set :tries to 0 then your block won't be called at all. You can use this to temporarialy disable all your retryable blocks:

retryable_options :tries => 0


Retryable retries any exception that inherits from StandardError. This catches most runtime errors (IOError, floating point) but lets most more catastrophic errors (missing method, nil reference) pass through without being retried.

Generally you only want to retry a few specific errors anyway:

:retryable(:on => [IOError, RangeError]) { ... }

You can certainly retry everything but, be warned, this is probably not what you want! Do you really want to retry method missing, out of memory, and a whole range of other errors that can't be fixed by trying again?

:retryable(:on => Exception) { ... }

More on Ruby exceptions:

You can also retry based on the exception message:

:retryable(:matching => /export/) { ... }

Block Parameters

Your block is called with two optional parameters: the number of tries until now, and the most recent exception.

retryable { |retries, exception|
  puts "try #{retries} failed: #{exception}" if retries > 0


retryable offers a little logging assistance if you specify a task.

retryable(:task => 'pick up sticks') { raise IOError }


pick up sticks
pick up sticks RETRY 1 because IOError

Use :logger to change the log message or destination:

retryable_options :logger => lambda { |task,retries,error|
    logger.error "retry #{task} #{retries}: #{error}" if retries > 0


Accidentally nesting callbacks can be a real problem. What you thought was a 6 minute maximum delay could end up being 36 minutes or worse. Nesting detection is off by default but it's easy to turn on.

retryable(:detect_nesting => true) {
  retryable { thread_needle }   # thread_needle will never be called

When Retryable detects a nested call it throws a Retryable::NestedException. This is not a StandardError, so it's not retried by default, and the error will propagate out.


Open an URL, retry up to two more times when an OpenURI::HTTPError occurs.

require "retryable"
require "open-uri"

include Retryable

retryable(:tries => 3, :on => OpenURI::HTTPError) do
  xml = open("").read

Print the default settings:

ruby -r ./lib/retryable.rb -e "include Retryable; puts Retryable.retryable_options.inspect"



MIT or public domain, your choice.


The story until now...

  • 2008 Cheah Chu Yeow wrote retryable as a monkeypatch to Kernel and wrote a blog post.
  • 2009 Carlo Zottmann converted it to a gem and made it a separate method.
  • 2010 Songkick converted it to a module and added :matching and :sleep.
  • 2011 Scott Bronson rebased it back onto Chu's repo, added flexible sleep and nesting detection.