Introduction

Gem::ConflictError occurs when two gems in your dependency tree require incompatible versions of the same dependency. RubyGems detects this at load time and raises the conflict, preventing your application from starting with an inconsistent gem environment.

Symptoms

  • Application crashes on startup with Gem::ConflictError
  • Error message shows two different version requirements for the same gem
  • bundle install succeeds but bundle exec rails server fails
  • The error appears after adding or updating a single gem

Example error output: `` Gem::ConflictError: Unable to activate faraday-1.10.3, because faraday-net_http-3.0.2 conflicts with faraday-net_http (~> 2.0) /path/to/gems/faraday-1.10.3/lib/faraday.rb:15:in <top (required)>' /path/to/gems/elasticsearch-transport-7.17.0/lib/elasticsearch/transport.rb:12:in <top (required)>'

Common Causes

  • A gem upgrade pulled in a major version bump of a shared dependency
  • Two gems require different major versions of a common library (e.g., faraday, activesupport)
  • Transitive dependencies create a version diamond with no resolvable intersection
  • Ruby version upgrade changed default gem versions

Step-by-Step Fix

  1. 1.Identify the conflicting gems:
  2. 2.```bash
  3. 3.bundle info faraday
  4. 4.bundle exec gem list faraday
  5. 5.`
  6. 6.View the full dependency tree:
  7. 7.```bash
  8. 8.bundle viz --image=dependencies.png
  9. 9.# Or use:
  10. 10.bundle exec ruby -e "require 'bundler'; Bundler.load.specs.each { |s| puts \"#{s.name} #{s.version}\" }"
  11. 11.`
  12. 12.Find which gems require the conflicting versions:
  13. 13.```bash
  14. 14.bundle exec ruby -e "
  15. 15.require 'bundler'
  16. 16.specs = Bundler.load.specs
  17. 17.specs.each do |spec|
  18. 18.spec.dependencies.each do |dep|
  19. 19.puts \"#{spec.name} #{spec.version} requires #{dep.name} #{dep.requirement}\" if dep.name == 'faraday-net_http'
  20. 20.end
  21. 21.end
  22. 22."
  23. 23.`
  24. 24.Resolve by pinning or upgrading the conflicting gem:
  25. 25.```ruby
  26. 26.# In Gemfile, add a version constraint to force compatibility
  27. 27.gem 'elasticsearch-transport', '~> 8.0' # Requires faraday-net_http ~> 3.0
  28. 28.`
  29. 29.Alternatively, use override in Bundler:
  30. 30.```ruby
  31. 31.# Force a specific version that satisfies all constraints
  32. 32.gem 'faraday-net_http', '~> 2.0'
  33. 33.`
  34. 34.Update the lock file:
  35. 35.```bash
  36. 36.bundle update faraday faraday-net_http elasticsearch-transport
  37. 37.`

Prevention

  • Run bundle outdated regularly to see version drift
  • Use bundle lock --add-platform to ensure consistent resolution across platforms
  • Add a Gemfile.lock diff check to your CI pipeline
  • Pin major versions explicitly rather than relying on pessimistic operators alone
  • Test gem upgrades in a staging environment before production deployment