Bundler Version Mismatch - Lockfile BUNDLED WITH in CI
By Daniel Zoghalchali·Latchkey
The Bundler version recorded in Gemfile.lock under BUNDLED WITH differs from the Bundler installed on the runner. Depending on the versions, Bundler warns, re-resolves, or refuses to run.
What this error means
bundle install warns that the lockfile was bundled with a different Bundler, or errors that you must use a specific Bundler major version. The gems are fine; the Bundler tool version is the mismatch.
bundler output
Warning: the running version of Bundler (2.4.10) is older than the version
that created the lockfile (2.5.6). We suggest you to upgrade to the version
that created the lockfile by running `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
Installed Bundler older than BUNDLED WITH
The lockfile records a newer Bundler than the runner has. Newer lockfile features may not be understood by the older Bundler, prompting a warning or upgrade request.
Bundler major-version gap
A Bundler 1.x lockfile on a Bundler 2.x runner (or the reverse) can be rejected outright with a "must use Bundler N" error.
How to fix it
Install the Bundler the lockfile pins
Match the runner Bundler to BUNDLED WITH.
Terminal
gem install bundler:2.5.6
bundle _2.5.6_ install
Or update the lockfile to the runner Bundler
If you prefer the installed Bundler, refresh BUNDLED WITH and commit.
Pin the Bundler version in CI to match BUNDLED WITH.
Commit lockfiles produced by a consistent Bundler version.
Let setup-ruby install the lockfile’s Bundler automatically (bundler: Gemfile.lock).
Frequently asked questions
What causes Bundler version mismatch?
There are 2 common causes: installed bundler older than bundled with and bundler major-version gap. The lockfile records a newer Bundler than the runner has.
How do I fix Bundler version mismatch?
There are 2 fixes depending on which cause you have: install the bundler the lockfile pins and or update the lockfile to the runner bundler. Work through them in order, since the first is the most common.
What does Bundler version mismatch actually mean?
bundle install warns that the lockfile was bundled with a different Bundler, or errors that you must use a specific Bundler major version.
How do I stop Bundler version mismatch happening again?
Pin the Bundler version in CI to match BUNDLED WITH. The prevention section lists 3 changes that keep it from recurring.
