Bundler "Bundler::GemNotFound" from a Stale Cache in CI

Bundler is running offline or against a vendored cache and cannot find a gem the lockfile requires. The cache predates a lockfile change, so the newly locked gem is not present locally.

What this error means

bundle install --local (or a cached/offline install) fails with Bundler::GemNotFound, naming a gem that is in Gemfile.lock but missing from vendor/cache. A fresh online install would succeed.

bundler output

Bundler::GemNotFound: Could not find rack-3.0.8 in any of the sources

Bundler tried to use the cache but rack-3.0.8 was not found in
vendor/cache.

Common causes

vendor/cache out of date with the lockfile

The lockfile added or bumped a gem but vendor/cache was not refreshed (bundle cache), so an offline install cannot find the new gem.

CI caching key did not change with the lockfile

A cache key not tied to Gemfile.lock restores a stale bundle, leaving the new gem absent on the runner.

How to fix it

Refresh the vendored cache

Re-cache the gems after any lockfile change and commit the result if you vendor gems.

Terminal

bundle cache
git add vendor/cache && git commit -m "Refresh vendored gems"

Key the CI cache on the lockfile

Tie the cache key to Gemfile.lock so a lockfile change invalidates a stale bundle.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: vendor/bundle
    key: gems-${{ hashFiles('Gemfile.lock') }}

How to prevent it

Run bundle cache after every lockfile change if you vendor gems.
Always key the gem cache on Gemfile.lock.
Avoid --local/offline installs unless the cache is guaranteed fresh.