Ruby Gem "required_ruby_version" Conflict in CI

A gem declares a required_ruby_version range in its gemspec, and the Ruby on your runner falls outside it. Bundler then cannot select that gem version - it is either too new or too old for your interpreter.

What this error means

bundle install or bundle update fails because a gem requires a Ruby version different from yours, or silently locks an ancient release that still supports your old Ruby and breaks at runtime.

Bundler could not find compatible versions for gem "ruby":
  In Gemfile:
    ruby 3.0.6

    some-gem (>= 2.0) was resolved to 2.1.0, which depends on
      ruby (>= 3.1.0)

Common causes

Interpreter older than the gem requires

Modern gem releases drop old Ruby versions. On Ruby 3.0 a gem requiring >= 3.1 cannot be selected, so Bundler reports a conflict or falls back to an old release.

Interpreter newer than the gem supports

Some gems cap their upper Ruby bound. On a brand-new Ruby they have no compatible release and the resolver fails.

How to fix it

Run the Ruby the gem supports

1. Read the required Ruby range in the conflict output.
2. Pin CI to a Ruby version inside every gem’s supported range with setup-ruby.
3. Confirm with ruby --version in the same job.

Or pin a gem release that supports your Ruby

If you cannot change Ruby, constrain the gem to a release that still supports it.

# Gemfile
gem 'some-gem', '~> 1.9'   # last line that supports Ruby 3.0

How to prevent it

• Keep your Ruby aligned with your gems’ supported ranges.
• Test against a CI matrix of the Ruby versions you support.
• Avoid tracking the newest Ruby release before your gems support it.

Related guides