Bun install cache corrupt / stale in CI

Bun caches downloaded packages under ~/.bun/install/cache. A partially written or mis-keyed cache restore can make bun install fail integrity checks or produce an inconsistent tree in CI.

What this error means

bun install fails with an integrity or extraction error, or installs an unexpected artifact, only after a cache restore, and passes on a clean cache.

Terminal

bun install
error: failed to extract package "esbuild" (cache may be corrupt)

Common causes

A truncated or partial cache restore

A cache saved mid-write or restored incompletely leaves a package half-extracted, so Bun cannot use it.

A cache key that outlives the lockfile

Keying the cache on something other than bun.lockb restores entries that no longer match the resolved dependencies.

How to fix it

Clear the Bun cache and reinstall

Remove the global install cache to drop corrupt entries.
Run bun install to repopulate it cleanly.
Re-run the job to confirm the tree is consistent.

Terminal

rm -rf ~/.bun/install/cache
bun install

Key the cache on bun.lockb

Cache the Bun store keyed on the lockfile hash so restores always match the resolved dependencies.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.bun/install/cache
    key: bun-${{ runner.os }}-${{ hashFiles('bun.lockb') }}

How to prevent it

Key the Bun cache on bun.lockb so it tracks resolved deps.
Clear ~/.bun/install/cache when integrity errors appear.
Avoid sharing a cache across different Bun versions.