ruby/ruby · error · Gem::Ext::BuildError

ERROR: Failed to build gem native extension. #{output}

Error message

ERROR: Failed to build gem native extension.

    #{output}

Gem files will remain installed in #{@gem_dir} for inspection.
Results logged to #{gem_make_out}

What it means

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).

Source

Thrown at lib/rubygems/ext/builder.rb:224

    end
  end

  ##
  # Logs the build +output+, then raises Gem::Ext::BuildError.

  def build_error(output, backtrace = nil) # :nodoc:
    gem_make_out = write_gem_make_out output

    message = <<-EOF
ERROR: Failed to build gem native extension.

    #{output}

Gem files will remain installed in #{@gem_dir} for inspection.
Results logged to #{gem_make_out}
EOF

    raise Gem::Ext::BuildError, message, backtrace
  end

  def build_extension(extension, dest_path) # :nodoc:
    results = []

    builder = builder_for(extension)

    extension_dir =
      File.expand_path File.join(@gem_dir, File.dirname(extension))
    lib_dir = File.join @spec.full_gem_path, @spec.raw_require_paths.first

    begin
      FileUtils.mkdir_p dest_path

      results = builder.build(extension, dest_path,
                              results, @build_args, lib_dir, extension_dir, @target_rbconfig, n_jobs: @build_jobs)

      verbose { results.join("\n") }

View on GitHub (pinned to 0e5b888e1c)

Solutions

1. 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.
2. Install prerequisites: build-essential plus Ruby dev headers (Linux), Xcode Command Line Tools (macOS), MSYS2/DevKit (Windows).
3. Check the gem's required Ruby version against yours and prefer a version shipping precompiled binaries for your platform.
4. Retry cleanly: `gem uninstall <gem>` then `gem install <gem>`, or `gem pristine --extensions <gem>`.

Example fix

# before: ruby:3.3-slim
gem install byebug   # ERROR: Failed to build gem native extension.
# after
apt-get update && apt-get install -y build-essential
gem install byebug

def native_toolchain?
  %w[make gcc].all? { |t| system("sh", "-c", "command -v #{t}", out: File::NULL) }
end

warn "native builds will fail without a toolchain" unless native_toolchain?

begin
  Gem::DependencyInstaller.new.install(gem_name)
rescue Gem::Ext::BuildError => e
  File.write("build-error.log", e.message)
  Gem::DependencyInstaller.new.install(gem_name, "< #{last_good_major}") # fall back to a buildable/prebuilt version
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• #{command_name || class_name} failed#{exit_reason}
• missing codepage argument
• unexpected debug option: %.*s\n
• too long: %s (max:%d)\n
• setup_debug_log failed (can't allocate memory)\n

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