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
the Tin Man
  • 158,662
  • 42
  • 215
  • 303
Dreams
  • 8,288
  • 10
  • 45
  • 71
  • 10
    In addition to the below answers its worth knowing that people use `raise` when handling exceptions and `fail` when not. – Bala Sep 15 '13 at 12:25
  • 6
    It's not a keyword, it's a method. – Jörg W Mittag Sep 16 '13 at 00:46
  • Documentation: [Kernel#fail](http://www.ruby-doc.org/core-2.1.1/Kernel.html#method-i-fail) – Jared Beck May 06 '14 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 '16 at 15:17

4 Answers4

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.

the Tin Man
  • 158,662
  • 42
  • 215
  • 303
crazybob
  • 2,307
  • 1
  • 21
  • 26
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
BinaryButterfly
  • 18,137
  • 13
  • 50
  • 91
kuboon
  • 9,557
  • 3
  • 42
  • 32
  • +1 for style advisory; even if they are identical semantically using each in their intended setting helps convey intention better – fatuhoku Mar 30 '17 at 15:06
  • Unfortunately, the link is not working any more. – Lindydancer Apr 07 '21 at 07:42
  • 1
    https://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 03 '23 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!"
Boris Stitnicky
  • 12,444
  • 5
  • 57
  • 74
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.

the Tin Man
  • 158,662
  • 42
  • 215
  • 303
pjs
  • 18,696
  • 4
  • 27
  • 56