{"record":{"id":"617c9055bebcb802","repo":"ruby/ruby","slug":"error-failed-to-build-gem-native-extension","errorCode":null,"errorMessage":"ERROR: Failed to build gem native extension.\n\n    #{output}\n\nGem files will remain installed in #{@gem_dir} for inspection.\nResults logged to #{gem_make_out}","messagePattern":"ERROR: Failed to build gem native extension\\.\n\n    #(.+?)\n\nGem files will remain installed in #(.+?) for inspection\\.\nResults logged to #(.+?)","errorType":"exception","errorClass":"Gem::Ext::BuildError","httpStatus":null,"severity":"error","filePath":"lib/rubygems/ext/builder.rb","lineNumber":224,"sourceCode":"    end\n  end\n\n  ##\n  # Logs the build +output+, then raises Gem::Ext::BuildError.\n\n  def build_error(output, backtrace = nil) # :nodoc:\n    gem_make_out = write_gem_make_out output\n\n    message = <<-EOF\nERROR: Failed to build gem native extension.\n\n    #{output}\n\nGem files will remain installed in #{@gem_dir} for inspection.\nResults logged to #{gem_make_out}\nEOF\n\n    raise Gem::Ext::BuildError, message, backtrace\n  end\n\n  def build_extension(extension, dest_path) # :nodoc:\n    results = []\n\n    builder = builder_for(extension)\n\n    extension_dir =\n      File.expand_path File.join(@gem_dir, File.dirname(extension))\n    lib_dir = File.join @spec.full_gem_path, @spec.raw_require_paths.first\n\n    begin\n      FileUtils.mkdir_p dest_path\n\n      results = builder.build(extension, dest_path,\n                              results, @build_args, lib_dir, extension_dir, @target_rbconfig, n_jobs: @build_jobs)\n\n      verbose { results.join(\"\\n\") }","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/ruby/ruby/blob/0e5b888e1c355f3f728f2659f085820937dada48/lib/rubygems/ext/builder.rb#L206-L242","documentation":"The umbrella error surfaced when any extension builder (extconf/cmake/rake) fails to build a gem's native extension during `gem install`/`gem pristine`. Gem::Ext::BuildError is raised from build_error with the full build output embedded, and states that the gem's files remain in the gem directory for inspection with everything logged to gem_make_out (ext/<gem>/<version>/gem_make_out).","triggerScenarios":"Any extension build failure during install: compile errors, missing headers, wrong Ruby version, missing toolchain — this is the user-facing wrapper around the underlying builder failure.","commonSituations":"Installing C-extension gems on slim images or systems without build tools; Ruby upgraded past a gem's supported range; macOS/Windows platform quirks; gems published without precompiled binaries.","solutions":["Read the embedded output first — it contains the actual compiler/extconf error, and the complete log persists in gem_make_out inside the gem's extension directory.","Install prerequisites: build-essential plus Ruby dev headers (Linux), Xcode Command Line Tools (macOS), MSYS2/DevKit (Windows).","Check the gem's required Ruby version against yours and prefer a version shipping precompiled binaries for your platform.","Retry cleanly: `gem uninstall <gem>` then `gem install <gem>`, or `gem pristine --extensions <gem>`."],"exampleFix":"# before: ruby:3.3-slim\ngem install byebug   # ERROR: Failed to build gem native extension.\n# after\napt-get update && apt-get install -y build-essential\ngem install byebug","handlingStrategy":"fallback","validationCode":"def native_toolchain?\n  %w[make gcc].all? { |t| system(\"sh\", \"-c\", \"command -v #{t}\", out: File::NULL) }\nend\n\nwarn \"native builds will fail without a toolchain\" unless native_toolchain?","typeGuard":null,"tryCatchPattern":"begin\n  Gem::DependencyInstaller.new.install(gem_name)\nrescue Gem::Ext::BuildError => e\n  File.write(\"build-error.log\", e.message)\n  Gem::DependencyInstaller.new.install(gem_name, \"< #{last_good_major}\") # fall back to a buildable/prebuilt version\nend","preventionTips":["Provision compilers and Ruby headers before installing C-extension gems.","Read gem_make.out in the gem's extension directory for complete build logs.","Cache built gems in Docker/CI to avoid recompiling on every run.","Prefer gems offering precompiled binaries for your platform in deployment images."],"tags":["rubygems","native-extensions","install","build-failure","compiler"],"backgroundTag":"native-extension-build-failed","analyzedSha":"0e5b888e1c355f3f728f2659f085820937dada48","analyzedAt":"2026-08-21T14:25:43.473Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}