# Ruby "Could not find 'bundler' (X) required by Gemfile.lock"

> Fix "Could not find 'bundler' (2.5.6) required by your /path/Gemfile.lock" in CI - install the exact Bundler version the lockfile demands.

Source: https://latchkey.dev/learn/ruby/ruby-bundler-version-not-found  
Updated: 2026-06-25

The lockfile requires a specific Bundler version and that exact version is not installed on the runner. RubyGems refuses to fall back to a different Bundler when the lockfile pins one.

## Diagnose it: Ruby version and platform

Bundler resolves against the Ruby version and the platform recorded in the lockfile. A runner on a different Ruby or a Linux platform missing from `Gemfile.lock` fails in a way that names a gem rather than the cause.

```Terminal
ruby -v && bundle -v
cat .ruby-version 2>/dev/null
bundle platform

# the usual CI-only failure: Linux platform absent from the lockfile
bundle lock --add-platform x86_64-linux
bundle install --jobs 4 --retry 3
```

> A gem that installs on macOS and fails on a Linux runner is usually a missing platform in `Gemfile.lock`, not a broken gem. Add the platform and commit the lockfile.

## FAQ

### What causes Ruby "Could not find 'bundler' (X) required by Gemfile.lock"?

There are 2 common causes: the pinned bundler is not installed and default bundler differs from the lockfile. Gemfile.lock’s BUNDLED WITH names a Bundler version the runner does not have, and RubyGems will not silently substitute a different one.

### How do I fix Ruby "Could not find 'bundler' (X) required by Gemfile.lock"?

There are 2 fixes depending on which cause you have: install the exact bundler version and let setup-ruby read the lockfile. Work through them in order, since the first is the most common.

### What does Ruby "Could not find 'bundler' (X) required by Gemfile.lock" actually mean?

A bundle command fails with "Could not find 'bundler' (X) required by your Gemfile.lock", listing the installed Bundler versions.

### How do I stop Ruby "Could not find 'bundler' (X) required by Gemfile.lock" happening again?

Have CI install the lockfile’s Bundler (bundler: Gemfile.lock). The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt