Fix: Ruby Bundler Version Conflict — Gemfile Requirements Could Not Be Resolved

The Problem

Bundler fails to resolve gem dependencies:

Bundler could not find compatible versions for gem "activesupport":
  In Gemfile:
    rails (~> 7.1.0) was resolved to 7.1.3, which depends on
      activesupport (= 7.1.3)

    sidekiq (>= 7.0) was resolved to 7.2.0, which depends on
      activesupport (>= 7.0, < 8.0)

    some-gem (~> 3.0) was resolved to 3.0.1, which depends on
      activesupport (< 7.0)

Or bundle install fails after adding a new gem:

Could not find gem 'some-new-gem (~> 2.0)' in locally installed gems.
Run `bundle install` to install missing gems.

Or the lockfile is out of sync on a different platform:

Your bundle only supports platforms ["x86_64-linux"] but your local platform
is aarch64-linux. Add the current platform to the lockfile with
`bundle lock --add-platform aarch64-linux` and try again.

Or Bundler itself is the wrong version:

Bundler 2.3.0 is running, but your lockfile was generated with 2.5.0.
Installing Bundler 2.5.0 and restarting using that version.

Why This Happens

Bundler resolves a set of gem versions that satisfies all constraints simultaneously. Conflicts arise from:

• Transitive dependencies with incompatible version ranges — gem A requires activesupport < 7.0 while gem B requires activesupport >= 7.0. No version of activesupport satisfies both.
• Outdated Gemfile.lock — the lockfile was generated on a different machine or with a different Bundler version. Some gems may have been removed from RubyGems or the platform doesn’t match.
• Platform-specific gems — gems with native extensions (nokogiri, grpc, pg) have platform-specific precompiled binaries. A lockfile generated on Linux may not have the macOS platform entry.
• Bundler version mismatch — different Bundler versions have different resolver algorithms. A lockfile generated with Bundler 2.5 may not resolve with Bundler 2.3.
• Overly strict version constraints — pinning gems to exact versions (gem 'rails', '7.0.4') prevents Bundler from finding compatible combinations when other gems need different patch versions.

Fix 1: Read the Conflict Error Carefully

The error message tells you exactly which gems conflict:

bundle install
# Read the full error — it shows the dependency chain:
# Bundler could not find compatible versions for gem "X":
#   In Gemfile:
#     gem_a requires X (~> 2.0)
#     gem_b requires X (>= 3.0)
# No version of X satisfies both constraints

# Or use verbose output for more detail
bundle install --verbose

Identify the conflicting gem pair:

# Check what version of a specific gem is currently installed
bundle info activesupport
gem list activesupport

# Check a gem's dependencies
gem dependency some-gem --remote

# View the dependency graph
bundle viz   # Requires graphviz — creates a dependency graph image
# Or text version:
bundle list

Fix 2: Update the Conflicting Gem

Try updating the specific gem that’s causing the conflict:

# Update a single gem and its dependencies
bundle update some-gem

# Update a gem without updating its dependencies (more conservative)
bundle update --conservative some-gem

# Update multiple gems at once
bundle update gem-a gem-b

# Check what would change before updating
bundle outdated
bundle outdated --strict   # Only show gems with updates within version constraints

After updating, check if the conflict is resolved:

bundle install   # Should succeed now

# Commit the updated Gemfile.lock
git add Gemfile.lock
git commit -m "Update Gemfile.lock after updating some-gem"

Fix 3: Relax Version Constraints in Gemfile

Overly strict constraints cause unnecessary conflicts:

# Gemfile — common constraint mistakes and fixes

# WRONG — exact version pin prevents updates
gem 'rails', '7.0.4'   # Only allows exactly 7.0.4

# BETTER — allow patch updates
gem 'rails', '~> 7.0.4'   # Allows 7.0.x (x >= 4)

# BETTER — allow minor updates
gem 'rails', '~> 7.0'   # Allows 7.x (x >= 0)

# WRONG — very old constraint blocks modern dependencies
gem 'some-gem', '~> 1.0'   # When 2.0+ is required by other gems

# CORRECT — check the gem's changelog and update the constraint
gem 'some-gem', '~> 2.0'

Use bundle exec to check if constraints work:

# Temporarily loosen a constraint to find a working version
# Then tighten it back after identifying the compatible range

# Check if removing version constraint resolves the conflict
# gem 'conflicting-gem'   # Remove version spec temporarily
bundle install   # Does it resolve?
bundle info conflicting-gem   # Note the version it chose
# Then: gem 'conflicting-gem', '~> X.Y'

Fix 4: Fix Platform-Specific Lockfile Issues

When working across different OS/CPU architectures:

# Check current platforms in Gemfile.lock
grep -A5 "PLATFORMS" Gemfile.lock

# Add missing platform
bundle lock --add-platform x86_64-linux
bundle lock --add-platform aarch64-linux   # ARM Linux (M1/M2 Mac in Docker)
bundle lock --add-platform x86_64-darwin   # Intel Mac
bundle lock --add-platform aarch64-darwin  # Apple Silicon Mac
bundle lock --add-platform x86_64-mingw-ucrt  # Windows

# Add all common platforms at once
bundle lock --add-platform \
  x86_64-linux \
  aarch64-linux \
  x86_64-darwin \
  aarch64-darwin

Configure Bundler to use platform-specific gems (nokogiri, grpc, etc.):

# Use precompiled platform gems instead of building from source
bundle config set force_ruby_platform false   # Default — use precompiled

# For CI/production where native compilation is unavailable:
bundle config set force_ruby_platform true    # Build from source always

Gemfile configuration for cross-platform gems:

# Gemfile
source 'https://rubygems.org'

# Force precompiled gems for faster installs across platforms
gem 'nokogiri', force_ruby_platform: false
gem 'grpc', force_ruby_platform: false

Fix 5: Fix Bundler Version Issues

Match the Bundler version to what generated the lockfile:

# Check Gemfile.lock for required Bundler version
grep "BUNDLED WITH" Gemfile.lock
# BUNDLED WITH
#    2.5.0

# Check your installed Bundler version
bundler --version   # or: bundle --version

# Install the required version
gem install bundler -v 2.5.0

# Run with a specific Bundler version
bundle _2.5.0_ install

# Update Bundler itself
gem update bundler

# Set Bundler version for the project
bundle config set --local bundler_version 2.5.0

Pin Bundler version in .ruby-version or .tool-versions:

# .ruby-version
3.3.0

# .tool-versions (asdf)
ruby 3.3.0
bundler 2.5.0

Fix 6: Nuclear Option — Regenerate the Lockfile

When the lockfile is badly out of sync, start fresh:

# CAUTION — this updates ALL gems to their latest compatible versions
# Make sure your tests pass after this

# Delete the lockfile and regenerate
rm Gemfile.lock
bundle install

# Or: update all gems at once (safer — keeps version constraints)
bundle update

# If specific gems should stay locked (e.g., Rails version)
# Make sure Gemfile specifies exact range:
# gem 'rails', '~> 7.1.0'   # Only updates patch versions
bundle update   # Updates everything else to latest compatible

# Run your test suite to catch regressions
rails test
# or: rspec

Compare what changed:

# After regenerating, see what versions changed
git diff Gemfile.lock

# Review major version bumps that might need code changes
git diff Gemfile.lock | grep "^[+-]" | grep -v "^[+-][+-][+-]"

Fix 7: Debug Dependency Resolution

When you can’t figure out why a gem is being pulled in:

# Find out why a gem is in your bundle
bundle info some-gem   # Shows the gem and who requires it

# List all gems and their dependencies
bundle list --paths   # Shows install paths

# Check if a gem is required directly or transitively
grep -r "some-gem" Gemfile Gemfile.lock

# Show the full dependency tree
bundle exec gem dependency --reverse-dependencies some-gem

# Check RubyGems.org for available versions
gem list some-gem --remote --all | head -20

# Find the highest version satisfying a constraint
gem list some-gem --remote | grep "^some-gem "

When a gem requires an incompatible Ruby version:

# Error: gem-name requires Ruby version >= 3.0
# Check your Ruby version
ruby --version

# Switch Ruby version with rbenv
rbenv install 3.3.0
rbenv local 3.3.0   # Set for this directory
bundle install

# Or with rvm
rvm install 3.3.0
rvm use 3.3.0
bundle install

Using a private gem server:

# Gemfile — multiple gem sources
source 'https://rubygems.org'

# Private gem server (e.g., GitHub Packages, Gemfury, Artifactory)
source 'https://rubygems.pkg.github.com/your-org' do
  gem 'private-gem', '~> 1.0'
end

# Configure credentials for private server
bundle config set --local https://rubygems.pkg.github.com/your-org \
  "username:ghp_yourtoken"

# Or set globally
bundle config set --global https://rubygems.pkg.github.com/your-org \
  "username:ghp_yourtoken"

Still Not Working?

Gems with the same name on different sources — if a gem exists on both RubyGems and a private server, Bundler may pick the wrong one. Use source blocks to be explicit about where each gem comes from.

bundle exec vs system commands — always run Ruby scripts and rake tasks with bundle exec to ensure the correct gem versions are used:

bundle exec rails server
bundle exec rspec
bundle exec rake db:migrate
# Without bundle exec — uses system gems, may conflict

Spring and Bundler — if using Spring (Rails process preloader), changes to gems require restarting Spring: spring stop then bundle exec rails server. Spring caches the gem environment.

Gemfile.lock in .gitignore — the lockfile should always be committed for applications (not libraries). If it’s gitignored, every developer gets different gem versions, causing “works on my machine” bugs. Libraries (gems themselves) should NOT commit Gemfile.lock.

For related Ruby issues, see Fix: Rails N+1 Query Problem and Fix: Ruby on Rails Migration Conflict.