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
signal, and others.
Quitting, which happens when the user types C-g, is not considered an error, but it is handled almost like an error. See Quitting.
SXEmacs has a rich hierarchy of error symbols predefined via
error syntax-error invalid-read-syntax list-formation-error malformed-list malformed-property-list circular-list circular-property-list invalid-argument wrong-type-argument args-out-of-range wrong-number-of-arguments invalid-function no-catch invalid-state void-function cyclic-function-indirection void-variable cyclic-variable-indirection invalid-operation invalid-change setting-constant editing-error beginning-of-buffer end-of-buffer buffer-read-only io-error end-of-file arith-error range-error domain-error singularity-error overflow-error underflow-error
The five most common errors you will probably use or base your new
errors off of are
invalid-change. Note the semantic differences:
syntax-erroris for errors in complex structures: parsed strings, lists, and the like.
invalid-argumentis for errors in a simple value. Typically, the entire value, not just one part of it, is wrong.
invalid-statemeans that some settings have been changed in such a way that their current state is unallowable. More and more, code is being written more carefully, and catches the error when the settings are being changed, rather than afterwards. This leads us to the next error:
invalid-changemeans that an attempt is being made to change some settings into an invalid state.
invalid-changeis a type of
invalid-operationrefers to all cases where code is trying to do something that’s disallowed. This includes file errors, buffer errors (e.g. running off the end of a buffer),
invalid-changeas just mentioned, and arithmetic errors.
This function signals a non-continuable error.
datum should normally be an error symbol, i.e. a symbol defined
define-error. args will be made into a list, and
datum and args passed as the two arguments to
the most basic error handling function.
This error is not continuable: you cannot continue execution after the
error using the debugger r command. See also
The correct semantics of args varies from error to error, but for most errors that need to be generated in Lisp code, the first argument should be a string describing the *context* of the error (i.e. the exact operation being performed and what went wrong), and the remaining arguments or \"frobs\" (most often, there is one) specify the offending object(s) and/or provide additional details such as the exact error when a file error occurred, e.g.:
For historical compatibility, DATUM can also be a string. In this case,
datum and args are passed together as the arguments to
format, and then an error is signalled using the error symbol
error and formatted string. Although this usage of
is very common, it is deprecated because it totally defeats the purpose
of having structured errors. There is now a rich set of defined errors
These examples show typical uses of
(error 'syntax-error "Dialog descriptor must supply at least one button" descriptor)
(error "You have committed an error. Try something else.") error→ You have committed an error. Try something else.
(error "You have committed %d errors." 10) error→ You have committed 10 errors.
If you want to use your own string as an error message verbatim, don’t
(error string). If string contains
‘%’, it will be interpreted as a format specifier, with undesirable
results. Instead, use
(error "%s" string).
This function behaves like
error, except that the error it
signals is continuable. That means that debugger commands c and
r can resume execution.
This function signals a continuable 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 SXEmacs Lisp classifies different sorts of
The number and significance of the objects in data depends on
error-symbol. For example, with a
error, there are two objects in the list: a predicate that describes the
type that was expected, and the object that failed to fit that type.
See 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
data) (see Handling Errors). If the error is not handled,
these two values are used in printing the error message.
signal can return, if the debugger is invoked and
the user invokes the “return from signal” option. If you want the
error not to be continuable, use
Note: In FSF Emacs
signal never returns.
(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 (no-such-error "My unknown error condition")
This function behaves like
signal, except that the error it
signals is not continuable.
This macro checks that argument satisfies predicate. If
that is not the case, it signals a continuable
wrong-type-argument error until the returned value satisfies
predicate, and assigns the returned value to argument. In
other words, execution of the program will not continue until
predicate is met.
argument is not evaluated, and should be a symbol. predicate is evaluated, and should name a function.
As shown in the following example,
check-argument-type is useful
in low-level code that attempts to ensure the sanity of its data before
(defun cache-object-internal (object wlist) ;; Before doing anything, make sure that wlist is indeed ;; a weak list, which is what we expect. (check-argument-type 'weak-list-p wlist) …)