emacs/doc/lispref/errors.texi

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1993, 1999, 2001--2025 Free Software Foundation,
@c Inc.
@c See the file elisp.texi for copying conditions.
@node Standard Errors
@appendix Standard Errors
@cindex standard errors

  Here is a list of the more important error symbols in standard Emacs, grouped
by concept.  The list includes each symbol's message and a cross reference
to a description of how the error can occur.

  Each error symbol has a set of parent error conditions that is a
list of symbols.  Normally this list includes the error symbol itself
and the symbol @code{error}.  Occasionally it includes additional
symbols, which are intermediate classifications, narrower than
@code{error} but broader than a single error symbol.  For example, all
the errors in accessing files have the condition @code{file-error}.  If
we do not say here that a certain error symbol has additional error
conditions, that means it has none.

  As a special exception, the error symbols @code{quit} and
@code{minibuffer-quit} don't have the condition @code{error}, because
quitting is not considered an error.

  Most of these error symbols are defined in C (mainly @file{data.c}),
but some are defined in Lisp.  For example, the file @file{userlock.el}
defines the @code{file-locked} and @code{file-supersession} errors.
Several of the specialized Lisp libraries distributed with Emacs
define their own error symbols.  We do not attempt to list of all
those here.

  @xref{Errors}, for an explanation of how errors are generated and
handled.

@table @code
@item error
The message is @samp{error}.  @xref{Errors}.

@item quit
The message is @samp{Quit}.  @xref{Quitting}.

@item minibuffer-quit
The message is @samp{Quit}.  This is a subcategory of @code{quit}.
@xref{Quitting}.

@item args-out-of-range
The message is @samp{Args out of range}.  This happens when trying to
access an element beyond the range of a sequence, buffer, or other
container-like object.  @xref{Sequences Arrays Vectors}, and see
@ref{Text}.

@item arith-error
The message is @samp{Arithmetic error}.  This occurs when trying to
perform integer division by zero.  @xref{Numeric Conversions}, and
see @ref{Arithmetic Operations}.

@item beginning-of-buffer
The message is @samp{Beginning of buffer}.  @xref{Character Motion}.

@item buffer-read-only
The message is @samp{Buffer is read-only}.  @xref{Read Only Buffers}.

@item circular-list
The message is @samp{List contains a loop}.  This happens when a
circular structure is encountered.  @xref{Circular Objects}.

@item cl-assertion-failed
The message is @samp{Assertion failed}.  This happens when the
@code{cl-assert} macro fails a test.  @xref{Assertions,,, cl, Common Lisp
Extensions}.

@item coding-system-error
The message is @samp{Invalid coding system}.  @xref{Lisp and Coding
Systems}.

@item cyclic-function-indirection
The message is @samp{Symbol's chain of function indirections contains
a loop}.  @xref{Function Indirection}.

@item cyclic-variable-indirection
The message is @samp{Symbol's chain of variable indirections contains
a loop}.  @xref{Variable Aliases}.

@item dbus-error
The message is @samp{D-Bus error}.  @xref{Errors and Events,,, dbus,
D-Bus integration in Emacs}.

@item end-of-buffer
The message is @samp{End of buffer}.  @xref{Character Motion}.

@item end-of-file
The message is @samp{End of file during parsing}.  Note that this is
not a subcategory of @code{file-error}, because it pertains to the
Lisp reader, not to file I/O@.  @xref{Input Functions}.

@item file-already-exists
This is a subcategory of @code{file-error}.  @xref{Writing to Files}.

@item permission-denied
This is a subcategory of @code{file-error}, which occurs when the OS
doesn't allow Emacs to access a file or a directory for some reason.

@item file-date-error
This is a subcategory of @code{file-error}.  It occurs when
@code{copy-file} tries and fails to set the last-modification time of
the output file.  @xref{Changing Files}.

@item file-error
We do not list the error-strings of this error and its subcategories,
because the error message is normally constructed from the data items
alone when the error condition @code{file-error} is present.  Thus,
the error-strings are not very relevant.  However, these error symbols
do have @code{error-message} properties, and if no data is provided,
the @code{error-message} property @emph{is} used.  @xref{Files}.

@item file-missing
This is a subcategory of @code{file-error}.  It occurs when an
operation attempts to act on a file that is missing.  @xref{Changing
Files}.

@c jka-compr.el
@item compression-error
This is a subcategory of @code{file-error}, which results from
problems handling a compressed file.  @xref{How Programs Do Loading}.

@c userlock.el
@item file-locked
This is a subcategory of @code{file-error}.  @xref{File Locks}.

@c userlock.el
@item file-supersession
This is a subcategory of @code{file-error}.  @xref{Modification Time}.

@c filenotify.el
@item file-notify-error
This is a subcategory of @code{file-error}.  It happens, when a file
could not be watched for changes.  @xref{File Notifications}.

@item remote-file-error
This is a subcategory of @code{file-error}, which results from
problems in accessing a remote file.  @xref{Remote Files,,, emacs, The
GNU Emacs Manual}.  Often, this error appears when timers, process
filters, process sentinels or special events in general try to access
a remote file, and collide with another remote file operation.  In
general it is a good idea to write a bug report.
@xref{Bugs,,, emacs, The GNU Emacs Manual}.

@c net/ange-ftp.el
@item ftp-error
This is a subcategory of @code{remote-file-error}, which results from
problems in accessing a remote file using ftp.  @xref{Remote Files,,,
emacs, The GNU Emacs Manual}.

@item invalid-function
The message is @samp{Invalid function}.  @xref{Function Indirection}.

@item invalid-read-syntax
The message is usually @samp{Invalid read syntax}.  @xref{Printed
Representation}.  This error can also be raised by commands like
@code{eval-expression} when there's text following an expression.  In
that case, the message is @samp{Trailing garbage following expression}.

@item invalid-regexp
The message is @samp{Invalid regexp}.  @xref{Regular Expressions}.

@c simple.el
@item mark-inactive
The message is @samp{The mark is not active now}.  @xref{The Mark}.

@item no-catch
The message is @samp{No catch for tag}.  @xref{Catch and Throw}.

@ignore
@c Not actually used for anything?  Probably definition should be removed.
@item protected-field
The message is @samp{Attempt to modify a protected file}.
@end ignore

@item range-error
The message is @code{Arithmetic range error}.

@item overflow-error
The message is @samp{Arithmetic overflow error}.  This is a subcategory
of @code{range-error}.
This can happen with integers exceeding the @code{integer-width} limit.
@xref{Integer Basics}.

@item scan-error
The message is @samp{Scan error}.  This happens when certain
syntax-parsing functions find invalid syntax or mismatched
parentheses.  Conventionally raised with three argument: a
human-readable error message, the start of the obstacle that cannot be
moved over, and the end of the obstacle.  @xref{List Motion}, and
see @ref{Parsing Expressions}.

@item search-failed
The message is @samp{Search failed}.  @xref{Searching and Matching}.

@item setting-constant
The message is @samp{Attempt to set a constant symbol}.  This happens
when attempting to assign values to @code{nil}, @code{t},
@code{most-positive-fixnum}, @code{most-negative-fixnum}, and keyword
symbols.  It also happens when attempting to assign values to
@code{enable-multibyte-characters} and some other symbols whose direct
assignment is not allowed for some reason.  @xref{Constant Variables}.

@c simple.el
@item text-read-only
The message is @samp{Text is read-only}.  This is a subcategory of
@code{buffer-read-only}.  @xref{Special Properties}.

@item undefined-color
The message is @samp{Undefined color}.  @xref{Color Names}.

@item user-error
The message is the empty string.  @xref{Signaling Errors}.

@item user-search-failed
This is like @samp{search-failed}, but doesn't trigger the debugger,
like @samp{user-error}.  @xref{Signaling Errors}, and see @ref{Searching
and Matching}.  This is used for searching in Info files, see @ref{Search
Text,,,info,Info}.

@item void-function
The message is @samp{Symbol's function definition is void}.
@xref{Function Cells}.

@item void-variable
The message is @samp{Symbol's value as variable is void}.
@xref{Accessing Variables}.

@item wrong-number-of-arguments
The message is @samp{Wrong number of arguments}.  @xref{Argument List}.

@item wrong-type-argument
The message is @samp{Wrong type argument}.  @xref{Type Predicates}.

@item unknown-image-type
The message is @samp{Cannot determine image type}.  @xref{Images}.

@item inhibited-interaction
The message is @samp{User interaction while inhibited}.  This error is
signaled when @code{inhibit-interaction} is non-@code{nil} and a user
interaction function (like @code{read-from-minibuffer}) is called.
@end table

@c The following seem to be unused now.
@ignore
  The following kinds of error, which are classified as special cases of
@code{arith-error}, can occur on certain systems for invalid use of
mathematical functions.  @xref{Math Functions}.

@table @code
@item domain-error
The message is @samp{Arithmetic domain error}.

@item singularity-error
The message is @samp{Arithmetic singularity error}.  This is a
subcategory of @code{domain-error}.

@item underflow-error
The message is @samp{Arithmetic underflow error}.  This is a
subcategory of @code{domain-error}.
@end table
@end ignore