Introduction

Ruby's Gem::ConflictError occurs when two different versions of the same gem are activated in the same process. This happens when dependencies require incompatible versions, often after updating one gem that pulls in a different version of a shared dependency than what another gem expects.

This error is common in Rails applications with many plugins, where gem version conflicts surface after running bundle update.

Symptoms

  • Application crashes with "Gem::ConflictError: Unable to activate X, because Y conflicts with Z"
  • Error shows which gem versions are in conflict
  • Application worked before running bundle update or adding a new gem

Common Causes

  • Two gems require different major versions of a shared dependency
  • bundle update upgraded a shared gem beyond what another gem supports
  • Gemfile specifies a version that conflicts with a transitive dependency

Step-by-Step Fix

  1. 1.Identify the conflicting gem versions: Use bundle to see the dependency tree.
  2. 2.```bash
  3. 3.# Show which gems depend on the conflicting gem:
  4. 4.bundle exec gem conflict rspec-core

# Or use bundler to show the dependency tree: bundle exec gem dependency rspec-core

# Check gemfile lock for actual versions: grep "rspec-core" Gemfile.lock ```

  1. 1.Resolve the conflict with explicit version constraints: Pin compatible versions.
  2. 2.```ruby
  3. 3.# Gemfile - specify compatible versions:
  4. 4.gem 'rspec-core', '~> 3.12'
  5. 5.gem 'rspec-rails', '~> 6.0'
  6. 6.gem 'rspec-mocks', '~> 3.12'

# Then update the lock file: bundle install

# If bundler still can't resolve, update specific gems: bundle update rspec-core rspec-rails rspec-mocks ```

  1. 1.Use bundle pristine to reset to locked versions: Clean up any local gem modifications.
  2. 2.```bash
  3. 3.# Reset all gems to versions in Gemfile.lock:
  4. 4.bundle pristine

# Or clean and reinstall everything: bundle install --force ```

Prevention

  • Commit Gemfile.lock to version control for reproducible dependencies
  • Run bundle install (not bundle update) in production deployments
  • Use conservative version constraints (~> x.y) instead of open ranges
  • Test gem updates in a separate branch before merging to main