---

41.5.1 Warning Basics

Every warning is a textual message, which explains the problem for the user, with the associated severity level which is a symbol. Here are the supported severity levels, in order of decreasing severity, and their meanings:

:emergency

A problem that will seriously impair Emacs operation soon if the user does not attend to it promptly.

:error

A report about data or circumstances that are inherently wrong.

:warning

A report about data or circumstances that are not inherently wrong, but raise suspicion of a possible problem.

:debug

A report of information that may be useful if the user is currently debugging the Lisp program which issues the warning.

When your program encounters invalid input data, it can either signal a Lisp error by calling error or signal (see How to Signal an Error) or report a warning with severity :error. Signaling a Lisp error is the easiest thing to do, but it means the signaling program cannot continue execution. If you want to take the trouble of implementing a way to continue processing despite the invalid data, then reporting a warning of severity :error is the right way of informing the user of the problem. For instance, the Emacs Lisp byte compiler can report an error that way and continue compiling other functions. (If the program signals a Lisp error and then handles it with condition-case, the user won’t see the error message; reporting that as a warning instead avoids that problem.)

In addition to severity level, each warning has a warning type to classify it. The warning type is either a symbol or a list of symbols. If it is a symbol, it should be the custom group that you use for the program’s user options; if it is a list, the first element of the list should be that custom group. For example, byte compiler warnings use the warning type (bytecomp). If the warning type is a list, the elements of the list after the first one, which should be arbitrary symbols, represent subcategories of the warning: they will be displayed to the user to better explain the nature of the warning.

Function: display-warning type message &optional level buffer-name ¶

This function reports a warning, using the string message as the warning text and type as the warning type. level should be the severity level, and defaults to :warning if omitted or nil.

buffer-name, if non-nil, specifies the name of the buffer for logging the warning message. By default, it is *Warnings*.

Function: lwarn type level message &rest args ¶

This function reports a warning using the value returned by (format-message message args…) as the message text in the *Warnings* buffer. In other respects it is equivalent to display-warning.

Function: warn message &rest args ¶

This function reports a warning using the value returned by (format-message message args…) as the message text, emacs as the warning type, and :warning as the severity level. It exists for compatibility only; we recommend not using it, because you should specify a specific warning type.