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

By Daniel Zoghalchali·Latchkey

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.

What this error means

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

bundler output

Could not find 'bundler' (2.5.6) required by your /app/Gemfile.lock.
To update to the latest version installed on your system, run `bundle update --bundler`.
To install the missing version, run `gem install bundler:2.5.6`.

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

Common causes

The pinned Bundler is not installed

Gemfile.lock’s BUNDLED WITH names a Bundler version the runner does not have, and RubyGems will not silently substitute a different one.

Default Bundler differs from the lockfile

The Ruby image ships one default Bundler; the project pins another. Without installing the pinned version, the command cannot run.

How to fix it

Install the exact Bundler version

Terminal

gem install bundler:2.5.6
bundle install

Let setup-ruby read the lockfile

setup-ruby can install the precise Bundler recorded in Gemfile.lock automatically.

.github/workflows/ci.yml

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.3.0'
    bundler: Gemfile.lock

How to prevent it

Have CI install the lockfile’s Bundler (bundler: Gemfile.lock).
Keep BUNDLED WITH consistent across the team.
Avoid hand-editing the BUNDLED WITH line in the lockfile.

Frequently asked questions

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.