How to exit a Ruby program

If you want your app to behave well in a unix environment, it's important that it exit correctly. In this post you'll learn all about unix exit codes, the mechanism that Ruby uses to exit a program, and how you can add custom behavior on exit.

As developers, we spend so much time on making our programs run that it's easy to overlook how they exit. And it's important! When your programs behave correctly on exit, it makes them a lot easier to manage and makes them more likely to work with standard devops tools.

There are a lot of ways that you can exit a Ruby program. I've shown some of them below. In this post we'll discuss the details of each of these, and how they can be used to make your app a well-behaved unix citizen.

# You can exit by calling a method
abort("She cannot take any more of this, Captain!")

# ...or by failing to catch an exception

# ...or by letting the program end naturally. :)

Exit codes, and YOU

Every program you run on Linux and OSX returns an exit status code when it's finished running. You don't normally see the exit code. It's used by the OS behind-the-scenes to determine if the program exited normally or if there was an error.

If you're using bash, you can see the exit code of the program that you just ran by examining the $? environment variable. The example below shows the exit code for a failure, then for a success.

% ls this-file-doesnt-exist
ls: this-file-doesnt-exist: No such file or directory
blog% echo $?
% ls .
% echo $?

Generally, the rule for unix-based systems is that zero means success. Nonzero means failure.

If you've ever used the &&   "operator" in bash, then  you've used status codes. In the example below, we tell bash to run program B only if program A was successful.

% a && b

You can use this trick in a lot of ways. For example, you might want to precompile assets, and upload them to a CDN.

blog% rake assets:precompile && rake cdn:upload_assets

Specifying an exit status with Ruby

Ruby takes care of a lot of the exit status stuff for us. If your program exits normally, it returns a "success" status. If it fails due to an uncaught exception, it gives a "failure" status. Below I'm showing the exit code for a script that raised an exception.

% ruby err.rb
err.rb:1:in `<main>': goodbye (RuntimeError)
tmp% echo $?

But what if you didn't want any uncaught exceptions? What if you wanted to exit cleanly, but still return a "failed" error code? Moreover, what if you wanted to return a custom code with an error message?

Fortunately, it's quite easy. Just pass an argument into the exit function. The argument can be a boolean or an integer. If it's boolean, then true means success. If it's an integer than 0 means success.

exit(true) # Exits with "success" code
exit(0) # Exits with "success" code

exit(false) # Exits with "failure" code
exit(1) # Exits with "failure" code

exit(436) # Custom failure error code

How exit works under the hood

The exit method simply raises a SystemExit exception. If it's uncaught, the program aborts just like it would with any other uncaught exception. That's pretty cool,  but there are some interesting consequences.

If you were to swallow all SystemExit exceptions, you'd break the exit method. I've shown this in the example below.

  exit 100
rescue SystemExit => e
  puts "Tried to exit with status #{ e.status }"

puts "...but it never exited, because we swallowed the exception"

# Outputs:
# Tried to exit with status 100
# ...but it never exited, because we swallowed the exception

This is yet another reason never to rescue Exception. Because SystemExit inherits from Exception, swallowing Exception will cause exit to break.

rescue Exception # never do this
  puts "I just broke the exit function!"

Human-readable error messages

While exit codes are great for machines, we humans often prefer a little bit of explanatory text. Fortunately, the OS provides us with an output stream specifically for things like error messages. Yep, I'm talking about STDERR.

You can write to STDERR just like you write to any IO object. In the example below I'm writing an error message and exiting with an "error" status.

STDERR.puts("ABORTED! You forgot to BAR the BAZ")

This being Ruby, there is of course a more concise way to write to stdout and exit with an error code. Just use the abort   method.

# Write the message to STDERR and exit with an error status code.
abort("ABORTED! You forgot to BAR the BAZ")

Callbacks via at_exit

Ruby lets you register handlers which can be called whenever the program exits. There can be more than one of them - they're called in the opposite order that they were registered in. Here's what it looks like:

at_exit do 
  puts "handler 1"

at_exit do 
  puts "handler 2"

# Outputs "handler2\nhandler1" on exit

The exit handler can override the exit code. You do this by calling exit from within the handler. Even though it seems like this should cause an infinite loop, it doesn't. :)

at_exit do 
  exit 100

exit 0

# This program exits with a code of 100

If you want to exit without calling any callbacks, you can do so via the exit! method. But keep in mind that this may cause problems if you have gems or other third-party code that depends on those callbacks.

An interesting aside

It turns out that lots of libraries use at_exit in inventive - and some might say hacky - ways. For example, Sinatra uses an at_exit hook to as a way to boot up the web app. This allows it to be sure that all your code has been loaded before it starts the server. Here's what it looks like:

module Sinatra
  class Application < Base


  at_exit {! if $!.nil? && }

There's a great post about this on the Arkency blog: Are we abusing at_exit?

What to do next:
  1. Try Honeybadger for FREE
    Honeybadger helps you find and fix errors before your users can even report them. Get set up in minutes and check monitoring off your to-do list.
    Start free trial
    Easy 5-minute setup — No credit card required
  2. Get the Honeybadger newsletter
    Each month we share news, best practices, and stories from the DevOps & monitoring community—exclusively for developers like you.
    author photo

    Starr Horne

    Starr Horne is a Rubyist and Chief JavaScripter at When she's not neck-deep in other people's bugs, she enjoys making furniture with traditional hand-tools, reading history and brewing beer in her garage in Seattle.

    More articles by Starr Horne
    Stop wasting time manually checking logs for errors!

    Try the only application health monitoring tool that allows you to track application errors, uptime, and cron jobs in one simple platform.

    • Know when critical errors occur, and which customers are affected.
    • Respond instantly when your systems go down.
    • Improve the health of your systems over time.
    • Fix problems before your customers can report them!

    As developers ourselves, we hated wasting time tracking down errors—so we built the system we always wanted.

    Honeybadger tracks everything you need and nothing you don't, creating one simple solution to keep your application running and error free so you can do what you do best—release new code. Try it free and see for yourself.

    Start free trial
    Simple 5-minute setup — No credit card required

    Learn more

    "We've looked at a lot of error management systems. Honeybadger is head and shoulders above the rest and somehow gets better with every new release."
    — Michael Smith, Cofounder & CTO of YvesBlue

    Honeybadger is trusted by top companies like:

    “Everyone is in love with Honeybadger ... the UI is spot on.”
    Molly Struve, Sr. Site Reliability Engineer, Netflix
    Start free trial