93

I am learning Ruby and encountered the fail keyword. What does it mean?

if password.length < 8
   fail "Password too short"
end
unless  username
   fail "No user name set"
end
4
  • 10
    In addition to the below answers its worth knowing that people use raise when handling exceptions and fail when not.
    – Bala
    Sep 15, 2013 at 12:25
  • 6
    It's not a keyword, it's a method. Sep 16, 2013 at 0:46
  • Documentation: Kernel#fail
    – Jared Beck
    May 6, 2014 at 15:52
  • Also note, you can write these as single line statements: fail "Password too short" if password.length < 8 and fail "No user name set" unless username
    – PhilT
    Feb 17, 2016 at 15:17

4 Answers 4

145

In Ruby, fail is synonymous with raise. The fail keyword is a method of the Kernel module which is included by the class Object. The fail method raises a runtime error just like the raise keyword.

The fail method has three overloads:

  • fail: raises a RuntimeError without an error message.

  • fail(string): raises a RuntimeError with the string argument as an error message:

    fail "Failed to open file"
    
  • fail(exception [, string [, array]]): raises an exception of class exception (first argument) with an optional error message (second argument) and callback information (third argument).

    Example: Assume you define a function which should fail if given a bad argument. It is better to raise an ArgumentError and not a RuntimeError:

    fail ArgumentError, "Illegal String"
    

    Another Example: You can pass the whole backtrace to the fail method so you can access the trace inside the rescue block:

    fail ArgumentError, "Illegal String", caller
    

    caller is a Kernel method which returns the backtrace as an array of strings in the form file:line: in 'method'.

With no arguments, raises the exception in $! or raises a RuntimeError if $! is nil. With a single String argument, raises a RuntimeError with the string as a message. Otherwise, the first parameter should be the name of an Exception class (or an object that returns an Exception object when sent an exception message). The optional second parameter sets the message associated with the exception, and the third parameter is an array of callback information. Exceptions are caught by the rescue clause of begin...end blocks.

Source: Ruby Documentation on the Kernel Module.

3
33

Rubocop says about usage of both words;

'Use fail instead of raise to signal exceptions.'

'Use raise instead of fail to rethrow exceptions.'

Here is an example.

def sample
  fail 'something wrong' unless success?
rescue => e
  logger.error e
  raise
end
3
  • +1 for style advisory; even if they are identical semantically using each in their intended setting helps convey intention better
    – fatuhoku
    Mar 30, 2017 at 15:06
  • Unfortunately, the link is not working any more. Apr 7, 2021 at 7:42
  • 1
    github.com/rubocop/ruby-style-guide#raise-vs-fail They seem to have updated the guideline. At the time of writing: Prefer raise over fail for exceptions.
    – matmat
    Mar 3, 2023 at 11:45
26

fail == raise

In other words, fail is just a popular alias for raise error-raising method. Usage:

fail ArgumentError, "Don't argue with me!"
7

www.ruby-doc.org is your friend. When I googled rubydoc fail "Kernel" was the first hit. My advice is, when in doubt, go to the definitive source for definitional stuff like this.

2
  • 2
    Woot, that really is a FAIL. Code example for fail is copy-paste from raise o_O Jan 17, 2014 at 21:00
  • 4
    @VajkHermecz fail is an alias of raise, so it reuses the documentation. Compare with the docs for Array#map and Array#collect Jun 12, 2014 at 17:55

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.