GNU Info

(elisp)Signaling Errors

---

Next: Processing of Errors Up: Errors

---

Enter node , (file) or (file)node

How to Signal an Error
......................

   Most errors are signaled "automatically" within Lisp primitives
which you call for other purposes, such as if you try to take the CAR
of an integer or move forward a character at the end of the buffer.
You can also signal errors explicitly with the functions `error' and
`signal'.

   Quitting, which happens when the user types `C-g', is not considered
an error, but it is handled almost like an error.  Note: Quitting.

   The error message should state what is wrong ("File does not
exist"), not how things ought to be ("File must exist").  The
convention in Emacs Lisp is that error messages should start with a
capital letter, but should not end with any sort of punctuation.

 - Function: error format-string &rest args
     This function signals an error with an error message constructed by
     applying `format' (Note: String Conversion) to FORMAT-STRING and
     ARGS.

     These examples show typical uses of `error':

          (error "That is an error -- try something else")
               error--> That is an error -- try something else
          
          (error "You have committed %d errors" 10)
               error--> You have committed 10 errors

     `error' works by calling `signal' with two arguments: the error
     symbol `error', and a list containing the string returned by
     `format'.

     *Warning:* If you want to use your own string as an error message
     verbatim, don't just write `(error STRING)'.  If STRING contains
     `%', it will be interpreted as a format specifier, with
     undesirable results.  Instead, use `(error "%s" STRING)'.

 - Function: signal error-symbol data
     This function signals an error named by ERROR-SYMBOL.  The
     argument DATA is a list of additional Lisp objects relevant to the
     circumstances of the error.

     The argument ERROR-SYMBOL must be an "error symbol"--a symbol
     bearing a property `error-conditions' whose value is a list of
     condition names.  This is how Emacs Lisp classifies different
     sorts of errors.

     The number and significance of the objects in DATA depends on
     ERROR-SYMBOL.  For example, with a `wrong-type-arg' error, there
     should be two objects in the list: a predicate that describes the
     type that was expected, and the object that failed to fit that
     type.  Note: Error Symbols, for a description of error symbols.

     Both ERROR-SYMBOL and DATA are available to any error handlers
     that handle the error: `condition-case' binds a local variable to
     a list of the form `(ERROR-SYMBOL .  DATA)' (Note: Handling
     Errors).  If the error is not handled, these two values are used
     in printing the error message.

     The function `signal' never returns (though in older Emacs versions
     it could sometimes return).

          (signal 'wrong-number-of-arguments '(x y))
               error--> Wrong number of arguments: x, y
          
          (signal 'no-such-error '("My unknown error condition"))
               error--> peculiar error: "My unknown error condition"

     Common Lisp note: Emacs Lisp has nothing like the Common Lisp
     concept of continuable errors.