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

The elpaca-info buffer will also contain a full log for the package, which is often useful for debugging and reporting issues.

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 and Environment

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

Please make sure you are filing bugs against stable versions of Emacs. Development versions of Emacs are not officially supported.

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.