Troubleshooting

Requesting Support

Please ensure you've read the manual, wiki, and searched previous issues before opening a new support ticket. The issue may already be covered.

Please be as specific as you can be when requesting support. At a minimum, the following should be in the issue ticket:

• The output of M-x elpaca-version
• What you expected to happen.
• What actually happened (including specific error message, backtrace, log output. No screenshots of text unless it is relevant to the bug/issue, please).

Inspecting Logs

If you are having trouble with a package, its often useful to check the elpaca-log buffer and search for the package(s) in question. For example, if the package "example" fails to build:

1. M-x elpaca-log
2. In the log buffer use the elpaca-ui-search command (bound to s by default)
3. Alter the search query to filter for log entries for the example package: example |.

Any log view can be quickly copied for pasting in an issue via the elpaca-ui-copy command (bound to c by default). Please use this command in favor of screen shots.

Inspecting Recipes

The elpaca-info command will show the menu-item recipe and the computed recipe (which accounts for any inheritance and modifications made to the recipe). Check to make sure the latter matches your expectations for what the recipe should be.

The elpaca-test Macro

Elpaca comes with the elpaca-test macro to make testing in a clean environment easier. Evaluating a test buffer will start a child Emacs process, install Elpaca and run the body of the test in a temporary environment. The test should be evaluated in a buffer with lexical-binding enabled and lisp-interaction-mode or emacs-lisp-mode enabled. Once the test has finished a for formatted results buffer will pop up. Please copy the entire contents of the results buffer, unaltered, when sharing results.

An example test result:

Test Case

(elpaca-test)

Host Env

elpaca	cbd7fae HEAD -> master, origin/master, origin/HEAD
isntaller	0.5
emacs	GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.38, cairo version 1.17.8) of 2023-08-18
git	git version 2.41.0

Output

  INFO     Scraping files for loaddefs... 
  INFO     Scraping files for loaddefs...done
  GEN      ../elpaca-autoloads.el
Cloning into '/tmp/elpaca.frall3/elpaca/repos/elpaca'...
Your branch is up to date with 'origin/master'.
Checking /tmp/elpaca.frall3/elpaca/repos/elpaca...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-info.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-log.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-manager.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-menu-elpa.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-menu-melpa.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-menu-org.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-process.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-test.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca-ui.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/elpaca.el...
Checking /tmp/elpaca.frall3/elpaca/repos/elpaca/doc...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/doc/early-init.el...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/doc/init.el...
Checking /tmp/elpaca.frall3/elpaca/repos/elpaca/extensions...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/extensions/elpaca-use-package.el...
Checking /tmp/elpaca.frall3/elpaca/repos/elpaca/images...
Checking /tmp/elpaca.frall3/elpaca/repos/elpaca/test...
Compiling /tmp/elpaca.frall3/elpaca/repos/elpaca/test/elpaca-test.el...
Done (Total of 11 files compiled, 3 skipped in 4 directories)

Downloading MELPA recipes...
Downloading MELPA recipes...100%
Downloading NonGNU-devel ELPA...
Downloading GNU-devel ELPA...
Downloading NonGNU ELPA...
Downloading GNU ELPA...

 Test Env

Elpaca cbd7fae HEAD -> master, origin/master, origin/HEAD
installer:      0.5
emacs-version:  GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.38, cairo version 1.17.8)
 of 2023-08-18
git --version:  git version 2.41.0

Backtraces

When Elpaca signals an error, it's often useful to be able to share what lead up to that error.

If the error occurs during the reading of the init file, starting Emacs from the command line with the --debug-init option. If the error is happening after that, either M-x toggle-debug-on-error or (setq debug-on-error t) prior to the error being signaled.

After doing one of those, a *Backtrace* buffer will appear when the error is signaled. Please copy the entire, untruncated output of that buffer when sharing. In order to get the full output (setq backtrace-line-length nil) prior to the error. You can also M-: (setq backtrace-line-length nil) in the *Backtrace* buffer, followed by the revert-buffer command.