ruby/ruby · error · ProductionError

The following gems are missing OS dependencies:

Error message

The following gems are missing OS dependencies:

What it means

`bundle doctor` scans installed gems for native-extension shared objects whose dynamic library dependencies are broken symlinks (broken_links). When any are found, CLI::Doctor::Diagnose (lib/bundler/cli/doctor/diagnose.rb:107) raises Bundler::ProductionError listing each gem and the missing path, meaning the OS-level shared libraries those native gems were linked against are no longer present at the expected location.

Source

Thrown at lib/bundler/cli/doctor/diagnose.rb:107

            lookup_with_fiddle(f)
          end
          if bad_paths.any?
            broken_links[spec] ||= []
            broken_links[spec].concat(bad_paths)
          end
        end
      end

      permissions_valid = check_home_permissions

      if broken_links.any?
        message = "The following gems are missing OS dependencies:"
        broken_links.flat_map do |spec, paths|
          paths.uniq.map do |path|
            "\n * #{spec.name}: #{path}"
          end
        end.sort.each {|m| message += m }
        raise ProductionError, message
      elsif permissions_valid
        Bundler.ui.info "No issues found with the installed bundle"
      end
    end

    private

    def check_home_permissions
      require "find"
      files_not_readable = []
      files_not_readable_and_owned_by_different_user = []
      files_not_owned_by_current_user_but_still_readable = []
      broken_symlinks = []
      Find.find(Bundler.bundle_path.to_s).each do |f|
        if !File.exist?(f)
          broken_symlinks << f
        elsif !File.readable?(f)
          if File.stat(f).uid != Process.uid

View on GitHub (pinned to 0e5b888e1c)

Solutions

1. Read the listed paths and install the OS package that provides each missing library (e.g. `brew install libxml2` or `apt install libxml2`)
2. Rebuild the affected native gem against current libraries: `gem pristine <gem>` or `bundle pristine <gem>`
3. Re-run `bundle doctor` to confirm, then `bundle install` if anything recompiled

Example fix

# before
$ bundle doctor
# => The following gems are missing OS dependencies:
#      * nokogiri: /usr/local/opt/libxml2/lib/libxml2.2.dylib

# after
$ brew install libxml2
$ bundle pristine nokogiri
$ bundle doctor

# CI pre-flight: fail early on missing OS libs before rspec does
system('bundle doctor') or abort 'Native dependencies broken — fix OS libraries first'

begin
  require 'nokogiri' # or the native gem in question
rescue LoadError => e
  warn 'Native gem failed to load — run `bundle doctor` for missing OS libraries'
  raise
end

When it happens

Trigger: Running `bundle doctor` after a macOS/OS upgrade, a Homebrew `brew cleanup`/prefix change, or a Linux distro upgrade that removed or moved .dylib/.so files that native gems (libxml2 in nokogiri, libssl, imagemagick, etc.) were linked against.

Common situations: Upgrading macOS and having nokogiri/sqlite3/pg suddenly fail with dyld errors; Homebrew removing old library versions; running in a container whose base image slimmed down shared libs after gems were compiled.

Related errors

• Your bundle only supports platforms #{@platforms.map(&:to_s)
• missing codepage argument
• Provide only one of the following options: #{patch_level.joi
• The options #{scopes.join " and "} were specified. Please on
• The #{flag} requires a lockfile. Please make sure you have c

AI-assisted analysis of ruby/ruby@0e5b888e1c (2026-08-21). Data as JSON: /api/errors/675538ac312eee91. Report an issue: GitHub.