Ruby "Failed to build gem native extension" in CI

gem install could not use a precompiled build for this platform and tried to compile the extension from source - and that compile failed, usually for a missing compiler or Ruby header.

What this error means

During install gem prints "Building native extensions. This could take a while..." then "ERROR: Failed to build gem native extension", followed by a make or compiler error. The failure is in the native build, not in RubyGems itself.

gem output

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

current directory: /usr/local/bundle/gems/nio4r-2.7.0/ext/nio4r
make: *** [Makefile:245: monitor.o] Error 1

Common causes

No precompiled gem for this platform or Ruby

When no platform-specific gem matches the runner, RubyGems falls back to building from source, which needs a working toolchain the runner may not have.

Missing compiler or development headers

The source build needs gcc/clang plus the Ruby headers (ruby-dev) and any library headers the gem links against. On a slim image those are absent.

How to fix it

Install the build toolchain and Ruby headers

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y build-essential ruby-dev
# Alpine
apk add --no-cache build-base ruby-dev

Prefer a precompiled platform gem

Many gems ship precompiled builds. Make sure the Linux platform is in your lockfile so Bundler picks the prebuilt gem instead of compiling.