Warnings and Errors

Common Warnings

"Unable to determine elpaca-core-date"

The elpaca-core-date variable is used when checking built-in package versions against MELPA's date-versioning scheme. This variable should be automatically set for supported Emacs releases. If you are running a development version of Emacs, you will see this warning. To fix it, set the elpaca-core-date variable to a YYYYMMDD version list corresponding to the build date for your Emacs version. This should be set before elpaca.el is loaded. Above the installer script is a good spot. e.g.

(setq elpaca-core-date '(20240101)) ;; This version of Emacs was built on 2024-01-01
;;Installer script below...

If you are running a stable release of Emacs (emacs-version only has two numbers. e.g. 27.1), this is likely a bug. Please report it.

Duplicate Item Warnings

Duplicate item queued: [ITEM]

If you encounter this warning, you most likely have multiple declarations attempting to queue the same item. e.g.

(use-package example)
;; later on...
(use-package example)

To fix this warning, combine the declarations into a single declaration:

(use-package example)

ITEM previously queued as a dependency of: (DEPENDENTS)

Elpaca normally queues all packages prior to processing any of them. This ensures the version of the package the user explicitly requests is installed even if a package declared before it needs that package as a dependency. e.g.

(elpaca a) ;; requires b
(elpaca (b :branch "development")) ;; this version of "b" is queued

elpaca-wait processes all of the queued packages up to the point it is called. Therefore, it can't know about packages which are queued after the point where it is called. e.g.

(elpaca a) ;; requires b
(elpaca-wait) ;; "a" is installed, "b" is installed as a dependency.
(elpaca b) ;; Elpaca warns about duplicate item here, because "b" has already been installed.

There are two ways to avoid this:

Rearrange declarations so a package's dependents come after it. e.g.

(elpaca b) ;; queued before "a's" dependencies are checked.
(elpaca a) ;; "b" already queued at this point.

A list of a package's dependents can be obtained via the elpaca-info or elpaca-dependents commands.

A better solution is to move all declarations which require elpaca-wait before other declarations. This way, blocking is minimized and the benefit of the queue system is maximized.

Installer Version Mismatch

"Elpaca installer version mismatch"

This means the version of the installer in your init file is out of date. To solve this, review the installer script, and replace the installer in your init with it. The warning should no longer appear after saving your init and restarting Emacs.

Feature loaded early

[feature name] loaded before Elpaca activation

This occurs when a feature is already loaded before Elpaca activates it. Usually this is a built-in feature. A common case:

The user loads their init file via org-babel-load-file. The built-in Org mode is loaded to use org-babel-load-file. Within the init file, Org is queued by Elpaca.

To fix this, either ensure that the feature is loaded after Elpaca has activated the package, or do not queue the package with Elpaca (see elpaca-ignored-dependencies if the package is being queued as a dependency of another).

Common Errors

"Unable to determine recipe URL"

The most likely cause of this is that a full recipe has not been provided. This can happen when a package has recently been added to an ELPA, but the user's menu for that ELPA has not been updated. Another cause could be the menu item cache has been corrupted. In either case, try M-x elpaca-update-menus and updating the menus before filing an issue for this error. You can use elpaca-info to see the menu-item and computed recipe for a package as well.

If you are seeing the error and the package recipe is your own, you need to provide either a :host and :repo or :repo URL to tell Elpaca where to download the package.

"Unable to find main elisp file"

This error is usually do to a package's main elisp file having an unusual naming convention or location. It can usually be solved by adding the :main recipe keyword to the package recipe.

Unmet dependency version

When a package dependency's version is too low, it's order will fail. The log info will show:

Requires PKGNAME minimum version VERSION

You can view both the dependent's minimum version requirements and each dependency's installed version via the elpaca-info command.

To fix this, first try updating the dependency mentioned by PKGNAME. If that does not work, check to see if the dependency is correctly reporting a version.

M-x elpaca-info PKGNAME

The version section of the info page should show a declared version (usually of the form "X.Y.Z") as well as a commit hash. If you only see a commit hash, you may need to modify the dependency's recipe to tell Elpaca how to get the version info.

In some cases (hl-todo, for example), package authors rely solely on git tags to record release information. This information cannot be found when a shallow clone is used. The recipe can be altered to use a full clone via the :depth recipe keyword. e.g.

(elpaca (hl-todo :depth nil))

Package authors commonly denote "version release tags" by prepending a version number with "v". e.g. "v1.0". This is not always the case, though. The :version-regexp keyword can be used to match/extract the meaningful version information from the repository's tags in those cases. For example:

;; Tags are "0.5", "0.6", "0.7"... no "v" prefix
(elpaca (key-chord :depth nil :version-regexp "\\(?:[[:digit:]]+\\.[[:digit:]]+\\)"))

If the package stores its main elisp file in a non-standard subdirectory, adding the :main recipe keyword should help:

(elpaca (PKGNAME :main "path/to/main/file.el"))

If the package does not store its version information in a PKGNAME-pkg.el file or the main elisp file's "Version" metadata header, adding the :version recipe keyword may help:

(elpaca (PKGNAME :version ;; function to return package's version...