## 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

```text
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