{"record":{"id":"675538ac312eee91","repo":"ruby/ruby","slug":"the-following-gems-are-missing-os-dependencies","errorCode":null,"errorMessage":"The following gems are missing OS dependencies:","messagePattern":"The following gems are missing OS dependencies:","errorType":"exception","errorClass":"ProductionError","httpStatus":null,"severity":"error","filePath":"lib/bundler/cli/doctor/diagnose.rb","lineNumber":107,"sourceCode":"            lookup_with_fiddle(f)\n          end\n          if bad_paths.any?\n            broken_links[spec] ||= []\n            broken_links[spec].concat(bad_paths)\n          end\n        end\n      end\n\n      permissions_valid = check_home_permissions\n\n      if broken_links.any?\n        message = \"The following gems are missing OS dependencies:\"\n        broken_links.flat_map do |spec, paths|\n          paths.uniq.map do |path|\n            \"\\n * #{spec.name}: #{path}\"\n          end\n        end.sort.each {|m| message += m }\n        raise ProductionError, message\n      elsif permissions_valid\n        Bundler.ui.info \"No issues found with the installed bundle\"\n      end\n    end\n\n    private\n\n    def check_home_permissions\n      require \"find\"\n      files_not_readable = []\n      files_not_readable_and_owned_by_different_user = []\n      files_not_owned_by_current_user_but_still_readable = []\n      broken_symlinks = []\n      Find.find(Bundler.bundle_path.to_s).each do |f|\n        if !File.exist?(f)\n          broken_symlinks << f\n        elsif !File.readable?(f)\n          if File.stat(f).uid != Process.uid","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/ruby/ruby/blob/0e5b888e1c355f3f728f2659f085820937dada48/lib/bundler/cli/doctor/diagnose.rb#L89-L125","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the listed paths and install the OS package that provides each missing library (e.g. `brew install libxml2` or `apt install libxml2`)","Rebuild the affected native gem against current libraries: `gem pristine <gem>` or `bundle pristine <gem>`","Re-run `bundle doctor` to confirm, then `bundle install` if anything recompiled"],"exampleFix":"# before\n$ bundle doctor\n# => The following gems are missing OS dependencies:\n#      * nokogiri: /usr/local/opt/libxml2/lib/libxml2.2.dylib\n\n# after\n$ brew install libxml2\n$ bundle pristine nokogiri\n$ bundle doctor","handlingStrategy":"validation","validationCode":"# CI pre-flight: fail early on missing OS libs before rspec does\nsystem('bundle doctor') or abort 'Native dependencies broken — fix OS libraries first'","typeGuard":null,"tryCatchPattern":"begin\n  require 'nokogiri' # or the native gem in question\nrescue LoadError => e\n  warn 'Native gem failed to load — run `bundle doctor` for missing OS libraries'\n  raise\nend","preventionTips":["Pin brew/apt library versions used at gem compile time","Run `bundle doctor` as a CI step after OS image changes","Rebuild native gems (`bundle pristine <gem>`) after every OS/Homebrew upgrade","Prefer bundler's vendored/compiled defaults (e.g. nokogiri --use-system-libraries off)"],"tags":["bundler","native-extensions","shared-libraries","doctor","os-dependencies"],"backgroundTag":"missing-native-library","analyzedSha":"0e5b888e1c355f3f728f2659f085820937dada48","analyzedAt":"2026-08-21T14:25:43.473Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}