# Bundler Version Mismatch - Lockfile BUNDLED WITH in CI

> Fix Bundler version mismatches in CI when the lockfile’s BUNDLED WITH differs from the installed Bundler - install the locked Bundler or update the lockfile.

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

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.

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

---

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