gem "Failed to build gem native extension" in CI

By Kaveh Alemi·Latchkey

A gem (nokogiri, pg, mysql2, ffi and similar) ships a C extension that Bundler compiles at install time. "Failed to build gem native extension" means the compile failed, usually for a missing compiler, Ruby headers, or a -dev library. The real error is in the mkmf output above.

What this error means

bundle install fails with "ERROR: Failed to build gem native extension" followed by a compiler or mkmf log, then "Gem::Ext::BuildError: ERROR: Failed to build gem native extension.".

Building native extensions. This could take a while...
ERROR:  Error installing ffi:
	ERROR: Failed to build gem native extension.

current directory: /vendor/bundle/ruby/3.3.0/gems/ffi-1.16.3/ext/ffi_c
make: command not found
Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

Common causes

No compiler or make on the runner

A slim image lacks build-essential, so gcc and make are missing and the extension cannot compile.

A missing -dev library or Ruby headers

The extension needs a system library header (or ruby-dev) that the image does not provide.

How to fix it

Install the build toolchain and headers

1. Read the mkmf log to see which tool or header is missing.
2. Install build-essential plus any named -dev package before bundling.
3. Re-run bundle install once the toolchain is present.

sudo apt-get update
sudo apt-get install -y build-essential ruby-dev

Use precompiled platform gems

Many gems ship precompiled binaries; lock the runner platform so no compilation happens.

bundle lock --add-platform x86_64-linux
bundle install

How to prevent it

• Install required -dev libraries before bundle install.
• Lock precompiled platforms so native builds are skipped in CI.
• Use a runner image that already includes the build toolchain.

Frequently asked questions

Related guides

References

• Bundler documentation
• GitHub Actions documentation