---

8.3 Reporting bugs ¶

If you think you have found a bug, we want to hear about it. Before reporting a bug, keep in mind that interaction with language servers represents a large quantity of unknown variables. Therefore, it is generally both difficult and absolutely essential that the maintainers reproduce bugs exactly as they happened to you, the user.

To report an Eglot bug, send e-mail to bug-gnu-emacs@gnu.org.

To understand how to write this email, get acquainted with Emacs’s bug reporting guidelines (see Bugs in GNU Emacs Manual). Then, follow this Eglot-specific checklist:

1. Include the transcript of JSONRPC events obtained from the buffer popped up by M-x eglot-events-buffer. You may narrow down the transcript if you are sure of where the problematic exchange is, but it’s safer to include the whole transcript, either attached or inline.
2. If Emacs signaled an error (an error message was seen or heard), make sure to repeat the process after turning on debug-on-error via M-x toggle-debug-on-error. This normally produces a backtrace of the error that should also be attached to the bug report.
3. Include a description of how the maintainer should obtain, install, and configure the language server you used. Maintainers usually have access to GNU/Linux systems, though not necessarily the distribution that you may be using. If possible, try to replicate the problem with the C/C++ or Python servers, as these are very easy to install.
4. If using an LSP multiplexer server like Rassumfrassum, first verify if the program replicates by using one of the multiplexed servers directly. If it doesn’t the problem lies in the LSP multiplexer program and should be reported there.
5. Include a description of a minimal project directory where Eglot should be started for the problem to happen. Describe each file’s name and its contents, or—sometimes better— zip that project directory completely and attach it. Alternatively, you can supply the address of a public Git repository.
6. Include versions of the software used. The Emacs version can be obtained with M-x emacs-version.

   We welcome bug reports about all Eglot versions, but it is helpful to first check if the problem isn’t already fixed in the latest version (see Getting the latest version).

   It’s also essential to include the version of ELPA packages that are explicitly or implicitly loaded. The optional but popular Company or Markdown packages are distributed as GNU ELPA packages, not to mention Eglot itself in some situations. Prefer reproducing the problem with built-in Treesit major modes like go-ts-mode or rust-ts-mode since the non-ts modes for such languages are usually provided by ELPA packages, and it’s often easy to miss them.

   If you can’t reproduce your bug without ELPA packages, you may find the ones you’re using in ~/.emacs.d/elpa (or what is in package-user-dir). Including a listing of files in that directory is a way to tell the maintainers about ELPA package versions.

7. Include a recipe to replicate the problem with a clean Emacs run. The invocation emacs -Q -f package-activate-all starts Emacs with no configuration and initializes the ELPA packages. A very minimal .emacs initialization file (10 lines or less) is also acceptable and good means to describe changes to variables.

   There is usually no need to include require statements in the recipe, as Eglot’s functionality uses autoloads.

   Likewise, there is rarely the need to use things like use-package or eglot-ensure. This just makes the recipe harder to follow. Prefer setting variables with setq and adding to hooks with add-hook. Prefer starting Eglot with M-x eglot.

8. Make sure to double check all the above elements and re-run the recipe to see that the problem is reproducible. Following the recipe should produce event transcript and error backtraces that are very similar to the ones you included. If the problem only happens sometimes, mention this in your report.

Please keep in mind that some problems reported against Eglot may actually be bugs in the language server or the Emacs feature/package that used Eglot to communicate with the language server. Eglot is, in many cases, just a frontend to that functionality.

Previous: Getting the latest version, Up: Troubleshooting Eglot [Contents][Index]