---

F.6.2.1 Error Signaling

Error Signaling Concepts

• ‘error’ signaling
• ‘error’ processing
• ‘error’ handling
• ‘error’ symbol
• ‘error’ message
• function error
• function signal

Signaling an error means beginning error processing. Error processing normally aborts all or part of the running program and returns to a point that is set up to handle the error.

Most ‘errors’ are signaled automatically within Lisp primitives. You can also signal ‘errors’ explicitly with the functions error and signal.

The error Function—The Error Message

‘error message’

Every ‘error’ specifies an ‘error message’. The message should state what is wrong, not how things ought to be. 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 ¶

The function error signals an ‘error’ with an ‘error message’. It works by calling signal with two arguments: the error symbol ‘error’, and a list containing the string returned by format-message.

error message

The eror message is constructed by applying format-message to ‘format-string’ and ‘args’. To signal with MESSAGE without interpreting format characters like ‘%’, ‘‘’ and ‘’’, use ‘(error "%s" MESSAGE)’.

The signal Function

Function: signal error-symbol data ¶

The function signal signals an ‘error’ named by ‘ERROR-SYMBOL’. It does not return.

If the ‘error’ is not handled, the two arguments (‘ERROR-SYMBOL’ and ‘DATA’) are used in printing an ‘error message’. Normally, this ‘error message’ is provided by the ‘error-message’ property of ‘ERROR-SYMBOL’. The number and significance of the objects in ‘DATA’ depend on ‘ERROR-SYMBOL’.

• ERROR-SYMBOL

  The argument ‘ERROR-SYMBOL’ must be an error symbol—a symbol defined with define-error. An error symbol is a symbol with an ‘error-conditions’ property that is a list of condition names.

• DATA The argument ‘DATA’ is a list of additional Lisp objects relevant to the circumstances of the ‘error’. Its elements are printed as part of the error message.

The user-error Function

Function: user-error format-string &rest args ¶

This function behaves exactly like error, except that it uses the error symbol ‘user-error’ rather than ‘error’. As the name suggests, this is intended to report errors on the part of the user, rather than errors in the code itself.