LilyPond Contributor's Guide: 10.6 Warnings, Errors, Progress and Debug Output

## 10.6 Warnings, Errors, Progress and Debug Output

### Available log levels

LilyPond has several loglevels, which specify how verbose the output on the console should be:

- NONE: No output at all, even on failure
- ERROR: Only error messages
- WARN: Only error messages and warnings
- BASIC_PROGRESS: Warnings, errors and basic progress (success, etc.)
- PROGRESS: Warnings, errors and full progress messages
- INFO: Warnings, errors, progress and more detailed information (default)
- DEBUG: All messages, including full debug messages (very verbose!)

The loglevel can either be set with the environment variable `LILYPOND_LOGLEVEL` or on the command line with the ‘`--loglevel=...`’ option.

### Functions for debug and log output

LilyPond has two different types of error and log functions:

- If a warning or error is caused by an identified position in the input file, e.g., by a grob or by a music expression, the functions of the `Input` class provide logging functionality that prints the position of the message in addition to the message.
- If a message can not be associated with a particular position in an input file, e.g., the output file cannot be written, then the functions in the `flower/include/warn.hh` file will provide logging functionality that only prints out the message, but no location.

There are also Scheme functions to access all of these logging functions from scheme. In addition, the Grob class contains some convenience wrappers for even easier access to these functions.

The message and debug functions in `warn.hh` also have an optional argument `newline`, which specifies whether the message should always start on a new line or continue a previous message. By default, `progress_indication` does NOT start on a new line, but rather continue the previous output. They also do not have a particular input position associated, so there are no progress functions in the Input class. All other functions by default start their output on a new line.

The error functions come in three different flavors: fatal error messages, programming error messages and normal error messages. Errors written by the `error ()` function will cause LilyPond to exit immediately, errors by `Input::error ()` will continue the compilation, but return a non-zero return value of the LilyPond call (i.e., indicate an unsuccessful program execution). All other errors will be printed on the console, but not exit LilyPond or indicate an unsuccessful return code. Their only differences to a warnings are the displayed text and that they will be shown with loglevel `ERROR`.

If the Scheme option `warning-as-error` is set, any warning will be treated as if `Input::error` was called.

### All logging functions at a glance

| C++, no location | C++ from input location
--- | --- | ---
ERROR | `error ()`, `programming_error (msg)`, `non_fatal_error (msg)` | `Input::error (msg)`, `Input::programming_error (msg)`
WARN | `warning (msg)` | `Input::warning (msg)`
BASIC | `basic_progress (msg)` | -
PROGRESS | `progress_indication (msg)` | -
INFO | `message (msg)` | `Input::message (msg)`
DEBUG | `debug_output (msg)` | `Input::debug_output (msg)`
| C++ from a Grob | Scheme, music expression
ERROR | `Grob::programming_error (msg)` | -
WARN | `Grob::warning (msg)` | `(ly:music-warning music msg)`
BASIC | - | -
PROGRESS | - | -
INFO | - | `(ly:music-message music msg)`
DEBUG | - | -
| Scheme, no location | Scheme, input location
ERROR | - | `(ly:error msg args)`, `(ly:programming-error msg args)`
WARN | `(ly:warning msg args)` | `(ly:input-warning input msg args)`
BASIC | `(ly:basic-progress msg args)` | -
PROGRESS | `(ly:progress msg args)` | -
INFO | `(ly:message msg args)` | `(ly:input-message input msg args)`
DEBUG | `(ly:debug msg args)` | -

#### LilyPond — Contributor’s Guide v2.24.4 (stable-branch).