Ruby "make failed, exit code 2" building a native gem in CI

After mkmf generates a Makefile for a gem’s C extension, make runs and exits non-zero. The error appears under gem install or bundle install for gems like nokogiri, pg, or mysql2, and the real cause is in the compiler output just above the make-failed line.

What this error means

Installing a native gem ends with "make failed, exit code 2" and a mkmf.log path. The lines above show the actual gcc/clang error - a missing header, an undefined symbol, or a failed library check.

bundler

current directory: /app/vendor/bundle/.../mysql2-0.5.5/ext/mysql2
make "DESTDIR=" clean
make "DESTDIR="
compiling client.c
client.c:1:10: fatal error: mysql.h: No such file or directory
make: *** [client.o] Error 1

make failed, exit code 2

Common causes

A required header or library is missing

The extension includes a system header (mysql.h, libxml2 headers, libpq-fe.h) that is not installed because the matching -dev package is absent.

Wrong or missing compiler/toolchain

gcc/clang or make is missing, or the available compiler rejects the gem’s C, so the build cannot complete.

How to fix it

Read mkmf.log and install the missing dev package

Open the mkmf.log path in the error to see exactly which header or library check failed.
Install the matching -dev package (e.g. libmysqlclient-dev, libpq-dev, libxml2-dev).
Re-run bundle install.

Install a toolchain and the dev libs up front

Make sure a compiler and the gem’s system dependencies are present before install.

Terminal

# Debian/Ubuntu example for mysql2
sudo apt-get update
sudo apt-get install -y build-essential default-libmysqlclient-dev
bundle install --jobs 4

How to prevent it

Install the gem’s -dev system libraries and a compiler before bundle install in CI.
Prefer precompiled platform gems where available (e.g. nokogiri ships them).
Use a runner image that already includes the native build dependencies your gems need.