ruby/rubygems · error · LockfileError

The Ruby version #{@locked_ruby_version} from #{@lockfile} c

Error message

The Ruby version #{@locked_ruby_version} from #{@lockfile} could not be parsed. Try running bundle update --ruby to resolve this.

What it means

Definition#locked_ruby_version_object parses the RUBY VERSION entry recorded in Gemfile.lock (@locked_ruby_version) with RubyVersion.from_string; when the recorded string does not match a recognized ruby/engine version format it raises Bundler::LockfileError advising `bundle update --ruby` (lib/bundler/definition.rb:464). The lockfile itself carries an uninterpretable Ruby version line: hand-edited, mangled by a merge, or written by tooling with a different format expectation.

Source

Thrown at lib/bundler/definition.rb:464

      rescue ReadOnlyFileSystemError
        raise ProductionError, lockfile_changes_summary("file system is read-only")
      end
    end

    def locked_ruby_version
      return unless ruby_version
      if @unlocking_ruby || !@locked_ruby_version
        Bundler::RubyVersion.system
      else
        @locked_ruby_version
      end
    end

    def locked_ruby_version_object
      return unless @locked_ruby_version
      @locked_ruby_version_object ||= begin
        unless version = RubyVersion.from_string(@locked_ruby_version)
          raise LockfileError, "The Ruby version #{@locked_ruby_version} from " \
            "#{@lockfile} could not be parsed. " \
            "Try running bundle update --ruby to resolve this."
        end
        version
      end
    end

    def bundler_version_to_lock
      @resolved_bundler_version || Bundler.gem_version
    end

    def to_lock
      require_relative "lockfile_generator"
      LockfileGenerator.generate(self)
    end

    def ensure_equivalent_gemfile_and_lockfile(explicit_flag = false)
      return unless Bundler.frozen_bundle?

View on GitHub (pinned to 86cbb817a3)

Solutions

Run `bundle update --ruby` as the message suggests to re-lock the ruby directive cleanly
Open Gemfile.lock and fix or delete the malformed RUBY VERSION block, then run `bundle install`
Check the Gemfile `ruby` directive itself for an invalid version string and correct it before re-locking
Last resort: delete Gemfile.lock and run `bundle install` to regenerate it, accepting a full re-resolution

Example fix

# before (Gemfile.lock)
RUBY VERSION
   ruby 3.2.

# after
RUBY VERSION
   ruby 3.2.2

Defensive patterns

Strategy: validation

Validate before calling

require "bundler/ruby_version"
lock = Bundler.default_lockfile.read
line = lock[/^RUBY VERSION\n\s+(\S.*)$/, 1]
if line && !Bundler::RubyVersion.from_string(line.strip)
  abort "unparsable RUBY VERSION in Gemfile.lock; run bundle update --ruby"
end

Try / catch

begin
  Bundler.definition.locked_ruby_version_object
rescue Bundler::LockfileError => e
  system("bundle", "update", "--ruby") || abort(e.message)
end

Prevention

Never hand-edit RUBY VERSION blocks; re-lock instead
Resolve Gemfile.lock conflicts by regenerating, not by merging text
Prevent CRLF mangles in lockfiles via .gitattributes or editor config

When it happens

Trigger: A Gemfile.lock whose RUBY VERSION block was edited badly or truncated; git merge conflicts resolved by hand around the RUBY VERSION section; lockfiles generated by string-concatenating scripts or by much older bundler versions; control characters or broken line endings corrupting the version line.

Common situations: Merge conflicts in Gemfile.lock resolved as raw text instead of re-locking; scripts that rewrite lockfiles without bundler; version jumps between very old and new bundler; CRLF conversions corrupting the section.

Related errors

AI-assisted analysis of ruby/rubygems@86cbb817a3 (2026-08-23). Data as JSON: /api/errors/bd4bf110a5c38eb2. Report an issue: GitHub.