Ruby Gem Build "make failed, exit code 2" in CI

"make failed, exit code 2" is the wrapper RubyGems prints when the extension’s Makefile build fails. The real cause - a missing library, an undefined symbol, or an incompatible header - is in the compiler output and mkmf.log above it.

What this error means

A native gem build prints a long compile log and ends with "make failed, exit code 2". The make wrapper is generic; the actual failure (a linker error, missing symbol, or library not found) appears earlier in the output.

build output

linking shared-object extension.so
/usr/bin/ld: cannot find -lz: No such file or directory
collect2: error: ld returned 1 exit status
make: *** [Makefile:245: extension.so] Error 1

make failed, exit code 2

Common causes

A library the extension links is missing

The compile succeeds but the link step fails - "cannot find -lz", "-lssl", etc. - because the system library it links against is not installed.

Incompatible headers or toolchain

A header version mismatch or a too-new/too-old compiler produces errors mid-build that surface only as the generic make failure.

How to fix it

Read mkmf.log and find the real error

Open the mkmf.log path printed above "make failed".
Find the first error/ld line - "cannot find -lXXX" maps to a missing -dev package.
Install that library (e.g. zlib1g-dev for -lz, libssl-dev for -lssl), then rebuild.

Install the missing library

Terminal

# Debian/Ubuntu - example for -lz and -lssl
apt-get update && apt-get install -y zlib1g-dev libssl-dev

How to prevent it

Bake the libraries your gems link against into the runner image.
Prefer precompiled platform gems that bundle their dependencies.
Keep the compiler toolchain consistent across CI and local.