bundler 'Your bundle is locked to X but that version could not be found in any of the sources' - how to fix

TL;DR

Gemfile.lock pins a gem version that no configured source serves anymore, usually yanked or removed. Run bundle update for that gem to move to a live version, then bundle install. Commit the updated Gemfile.lock.

Error

bundler 'Your bundle is locked to X but that version could not be found in any of the sources'  -  how to fix

Steps

1. Check the version's status: look the gem up on the source; yanked versions explain this instantly. Expected output: You know whether the version was yanked or the source changed.

2. Check the sources in the Gemfile: a source added, removed, or reordered since the lock was written changes what bundle can see. Expected output: You know which source should serve the gem.

3. Update the gem: bundle update [gem name]. Expected output: Bundler resolves the gem to a version the sources serve and rewrites the lockfile.

4. Install cleanly: bundle install. Expected output: The bundle installs with no missing-version errors.

5. Review and commit: git diff Gemfile.lock, then commit. Expected output: The lockfile diff is scoped to the gem move and CI installs green.

When to use

• bundle install fails with locked to X but that version could not be found in any of the sources
• A gem version was yanked after the lockfile was written
• The Gemfile's sources changed since the last lock

When not to use

• Bundler reports a version conflict; that is resolution, not a missing version
• The failure is a platform mismatch; check the gem's platform support instead
• Network errors reach the source; fix connectivity first

Variant phrasings

bundle install fails for a yanked gem version

The yank shape; bundle update moves to the nearest live version.

Locked version missing after changing gem sources

The source shape; the new source set never carried that version.

Could not find gem in any of the sources on CI only

CI may use a different source mirror; align the Gemfile sources or the mirror.

Why it happens

The lockfile is a snapshot of versions that existed when it was written. Gems get yanked, sources get reconfigured, and mirrors lag; when the snapshot references a version no current source serves, bundler stops rather than silently substitute a different version.

Edge cases

• bundle update without a gem name updates everything; always name the gem to keep the blast radius small.
• Private gem servers need credentials configured for bundle; a 401 can masquerade as a missing version.
• If the yanked version is load-bearing, vendor the gem or fork it rather than pinning a dead version.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IuNuQ4ioS7hlkSjl2Y9F2w