Troubleshooting

Recommended First Steps

Try these first before requesting support:

Check your Network Connection

Elpaca pulls package recipes from various websites. You need to be connected to the internet during the initial install and during most package installations. Occasionally, a website (gnu.org, github.com, etc) will experience downtime. Double check that you can connect to these sites with your web browser.

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 |.

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. If the recipe is missing, the menu item cache may be out of date or corrupted. Try M-x elpaca-update-menus in that case.

Check the *Warnings* Buffer

Elpaca may emit warnings in some cases. These can be found in the *Warnings* buffer.

Don't delete everything!

It may seem easiest to remove the entire elpaca directory and start from scratch. This is only necessary in rare cases, and is wasteful in every other case. It's better to delete a single package via M-x elpaca-delete. You can also manually remove a single package by deleting it's folder under $BUILDS/package-name and $REPOS/package-name. If the package is declared in your init file, Elpaca should reinstall on the next start of Emacs.

Rule out your configuration

You can easily test Elpaca in a clean environment via the elpaca-test macro.

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).

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.

Testing

The elpaca-test Macro

Elpaca comes with the elpaca-test macro to make testing in a clean environment easier. Evaluating a test form 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 lisp-interaction-mode buffer or emacs-lisp-mode buffer with lexical-binding 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. Tests can also be run interactively by adding :interactive t to the test declaration.

An example test result:

Test Case

(elpaca-test)

Host Env

elpaca	cbd7fae HEAD -> master, origin/master, origin/HEAD
installer	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

Prefer text over screenshots

Unless the issue is specifically graphical, please copy the text of any output, logs, etc instead of sharing images of the text. Text is searchable and easier to copy/paste/manipulate.