Bundler "Gem::Ext::BuildError" - Fix Native Build Failures in CI

Bundler installed a gem with a C extension and the compile step failed. Gem::Ext::BuildError is the wrapper - the real error (missing compiler, header, or library) is in the build log just above it.

What this error means

bundle install stops with "An error occurred while installing <gem>", then Gem::Ext::BuildError and "Failed to build gem native extension". The pure-Ruby part is fine; the native compile cannot complete.

bundler output

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

current directory: /usr/local/bundle/gems/ffi-1.16.3/ext/ffi_c
make: *** [Makefile:250: ffi.o] Error 1

An error occurred while installing ffi (1.16.3), and Bundler cannot continue.

Common causes

No build toolchain or Ruby headers

The gem needs gcc/clang plus the Ruby development headers (ruby-dev / ruby-devel) to compile its extension. Slim images often omit them.

A missing system library or its headers

Gems like pg (libpq) or nokogiri (libxml2/libxslt) link against system libraries whose -dev packages must be present at build time.

How to fix it

Read the real error above the wrapper

Open mkmf.log (the path is printed) and find the first error line.
Install the missing compiler, Ruby headers, or library -dev package it names.
Re-run bundle install once the dependency is present.

Install the toolchain and common headers

Terminal

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

How to prevent it

Bake build-essential, ruby-dev, and your gems’ system libraries into the runner image.
Pin gems to versions that ship precompiled platform gems where possible.
Keep a lockfile so the same native gems build the same way every run.