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

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

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.