yarn "An unexpected error occurred: … ENOENT" - Fix in CI

By Kaveh Alemi·Latchkey

ENOENT means "no such file or directory". When yarn wraps it in "An unexpected error occurred", a path yarn relied on - a cache dir, a temp file, a package tarball - was missing or removed mid-run.

What this error means

yarn install aborts with "An unexpected error occurred" followed by an ENOENT for some path. It often involves the yarn cache, a temp directory, or a file a lifecycle script expected to exist.

yarn output

error An unexpected error occurred:
"ENOENT: no such file or directory, open '/usr/local/share/.cache/yarn/v6/...'".

Diagnose it: which registry, and with what credentials?

Registry errors are resolved in a precedence chain, and the effective value is rarely the one in the file you are looking at. Scoped registries, .npmrc files at several levels, and environment variables all combine before a request is made.

Terminal

# the effective, fully merged configuration
npm config list -l | grep -E "registry|_auth|always-auth"

# where each value came from
npm config get registry
npm config get @yourscope:registry

# prove the token works, independently of the install
curl -sI -H "Authorization: Bearer $NPM_TOKEN" \
  "$(npm config get registry)@yourscope%2fpackage" | head -1

Common causes

A missing or partially restored cache directory

A CI cache that restored incompletely, or a cache path that was cleaned mid-run, leaves yarn looking for files that are not there.

A lifecycle script references a non-existent path

A postinstall or prepare step that cds into or reads a file that does not exist in CI surfaces as an ENOENT inside yarn’s run.

Concurrent processes touching the same cache

Two yarn runs sharing one cache dir can delete/move files out from under each other, producing transient ENOENT.

How to fix it

Reset the cache and reinstall cleanly

Clear the yarn cache and remove node_modules before retrying.

Terminal

yarn cache clean
rm -rf node_modules
yarn install --immutable

Isolate and validate paths

Give parallel jobs separate yarn cache directories.
Make lifecycle scripts tolerant of missing optional paths.
Verify the CI cache key restores a complete cache (or skip restoring a broken one).

How to prevent it

Use isolated cache dirs for parallel installs.
Validate paths in lifecycle scripts before using them.
Bust incomplete CI caches rather than restoring them.

Frequently asked questions

What causes yarn "An unexpected error occurred: … ENOENT"?

There are 3 common causes: a missing or partially restored cache directory, a lifecycle script references a non-existent path, and concurrent processes touching the same cache. A CI cache that restored incompletely, or a cache path that was cleaned mid-run, leaves yarn looking for files that are not there.

How do I fix yarn "An unexpected error occurred: … ENOENT"?

There are 2 fixes depending on which cause you have: reset the cache and reinstall cleanly and isolate and validate paths. Work through them in order, since the first is the most common.

What does yarn "An unexpected error occurred: … ENOENT" actually mean?

yarn install aborts with "An unexpected error occurred" followed by an ENOENT for some path.

How do I stop yarn "An unexpected error occurred: … ENOENT" happening again?

Use isolated cache dirs for parallel installs. The prevention section lists 3 changes that keep it from recurring.