Skip to content
Back to top
View this page
Edit this page

# Interact with errors

There are a couple of things that you can do with Flycheck errors in a buffer:

- You can navigate to errors, and go to the next or previous error.

- You can display errors to read their error messages.

- You can put error messages and IDs into the kill ring.

This section documents the corresponding commands and their customisation options.

## Navigate errors

By default Flycheck hooks into Emacs’ standard error navigation on `M`-`g` `n` (`next-error`) and `M`-`g` `p` (`previous-error`). When `Flycheck Mode` is enabled these commands will jump to the next and previous Flycheck error respectively. See :infonode:`(emacs)Compilation Mode` for more information about these commands.

This way you don’t need to learn special keybindings to navigate Flycheck errors; navigation should just work out of the box.

Note

Visible compilation buffers such as buffers from `M-x compile`, `M-x grep`, etc. still take precedence over Flycheck’s errors.

The exact behaviour of these error navigation features is very context-dependent and can be very confusing at times so you can disable this integration:

defcustom flycheck-standard-error-navigation

  Whether to integrate Flycheck errors into Emacs’ standard error navigation. Defaults to `t`, set to `nil` to disable.

  Important

  When changing the value you must disable `Flycheck Mode` and enable it again for the change to take effect in any buffers where `Flycheck Mode` is enabled.

Flycheck provides an independent set of navigation commands which will always navigate Flycheck errors in the current buffer, regardless of visible compilation buffers and `flycheck-standard-error-navigation`:

C-c ! n
M-x flycheck-next-error

  Jump to the next error.

  With prefix argument jump forwards by as many errors as specified by the prefix argument, e.g. `M`-`3` `C`-`c` `!` `n` will move to the 3rd error from the current point. With negative prefix argument move to previous errors instead. Signal an error if there are no more Flycheck errors.

C-c ! p
M-x flycheck-previous-error

  Jump to the previous Flycheck error.

  With prefix argument jump backwards by as many errors as specified by the prefix argument, e.g. `M`-`3` `C`-`c` `!` `p` will move to the 3rd error before the current point. With negative prefix argument move to next errors instead. Signal an error if there are no more Flycheck errors.

M-x flycheck-first-error

  Jump to the first Flycheck error.

  With prefix argument, jump forwards by as many errors as specified by the prefix argument, e.g. `M`-`3` `M`-`x` `flycheck`-`first`-`error` moves to the 3rd error from the beginning of the buffer. With negative prefix argument move to the last error instead.

By default error navigation jumps to all errors but you can choose to skip over errors with low levels:

defcustom flycheck-navigation-minimum-level

  The minimum levels of errors to consider for navigation.

  If set to an error level only navigate to errors whose level is as least as severe as this one. If `nil` navigate to all errors.

## Display errors

Whenever you move point to an error location Flycheck automatically displays all Flycheck errors at point after a short delay which you can customise:

defcustom flycheck-display-errors-delay

  The number of seconds to wait before displaying the error at point. Floating point numbers can express fractions of seconds.

You can also disable Flycheck from automatically displaying errors at point by customising:

defcustom flycheck-auto-display-errors-after-checking

  Whether to automatically display errors at the current point after checking.

  When being set to `nil`, it will prevent Flycheck from automatically displaying error messages. This setting is useful when Flycheck is used together with `flycheck-posframe`, to prevent `flycheck-posframe` from repeatedly displaying errors at point.

By default Flycheck shows the error messages in the minibuffer or in a separate buffer if the minibuffer is too small to hold the whole error message but this behaviour is entirely customisable:

defcustom flycheck-display-errors-function

  A function to display errors.

  The function is given the list of Flycheck errors to display as sole argument and shall display these errors to the user in some way.

Flycheck provides two built-in functions for this option:

defun flycheck-display-error-messages errors
defun flycheck-display-error-messages-unless-error-list errors

  Show error messages and IDs in the echo area or in a separate buffer if the echo area is too small (using `display-message-or-buffer` which see). The latter only displays errors when the error list is not visible. To enable it add the following to your init file:

      (setq flycheck-display-errors-function
            #'flycheck-display-error-messages-unless-error-list)

Along the same vein, Flycheck provides a way to customise how an error message is cleared, this is especially useful if you use a Flycheck extension to display error messages differently from the default.

defcustom flycheck-clear-displayed-errors-function

  Function to hide error message displayed by `flycheck-display-errors-function`.

  If set to a function, it will be called with no arguments to clear all displayed errors at point.

By default, Flycheck only provides `flycheck-clear-displayed-error-messages` to clear the last Flycheck error message from the minibuffer:

defun flycheck-clear-displayed-error-messages

  Clear error messages displayed by `flycheck-display-error-messages`.

See also

https://github.com/flycheck/flycheck-pos-tip

  A Flycheck extension to display errors in a GUI popup.

Additionally Flycheck shows errors in a GUI tooltip whenever you hover an error location with the mouse pointer. By default the tooltip contains the messages and IDs of all errors under the pointer, but the contents are customisable:

defcustom flycheck-help-echo-function

  A function to create the contents of the tooltip.

  The function is given a list of Flycheck errors to display as sole argument and shall return a single string to use as the contents of the tooltip.

## Errors from other files

Some checkers may return errors from files other than the current buffer (e.g., `gcc` may complain about errors in included files). These errors appear in the error list, and are also added on the first line of the current buffer. You can jump to the incriminating files with `flycheck-previous-error`.

By default, warnings and info messages from other files are ignored, but you can customize the minimum level:

defcustom flycheck-relevant-error-other-file-minimum-level

  The minimum level errors from other files to consider for inclusion in the current buffer.

  If set to an error level, only display errors from other files whose error level is at least as severe as this one. If `nil`, display all errors from other files.

To never show any errors from other files, set `flycheck-relevant-error-other-file-show` to `nil`.

defcustom flycheck-relevant-error-other-file-show

  Whether to show errors from other files.

## Explain errors

Flycheck also has the ability to display explanations for errors, provided the error checker is capable of producing these explanations. While several checkers produce explanations, the majority do not. Those that do are:

- `css-stylelint`

- `javascript-eslint`

- `markdown-markdownlint-cli`

- `markdown-markdownlint-cli2`

- `perl-perlcritic`

- `python-pylint`

- `python-ruff`

- `rpm-rpmlint`

- `rust`

- `rust-cargo`

- `rust-clippy`

- `sh-shellcheck`

C-c ! e
M-x flycheck-explain-error-at-point

  Display an explanation for the first explainable error at point.

## Kill errors

You can put errors into the kill ring with `C-c ! C-w`:

C-c ! C-w
M-x flycheck-copy-errors-as-kill

  Copy all messages of the errors at point into the kill ring.

C-u C-c ! C-w
C-u M-x flycheck-copy-errors-as-kill

  Like `C-c ! C-w` but with error IDs.

M-0 C-c ! C-w
M-0 M-x flycheck-copy-errors-as-kill

  Like `C-c ! C-w` but do not copy the error messages but only the error IDs.