Ruby "mkmf.rb can't find header files for ruby" in CI

A gem's extension is being compiled and mkmf needs the Ruby development headers, which are not installed. The headers live in the ruby-dev/ruby-devel package, not the base interpreter.

What this error means

During a native gem build, mkmf stops immediately with "can't find header files for ruby" and points at a missing rbconfig.rb or header directory. Ruby itself runs fine; only the headers needed to compile against it are absent.

mkmf output

checking for ruby/version.h... no
mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

You might have to install separate package for the ruby development
environment, ruby-dev or ruby-devel for example.

Common causes

Ruby development headers not installed

The base Ruby package does not include the C headers. Compiling any gem extension requires the separate dev package (ruby-dev on Debian/Ubuntu, ruby-devel on RHEL/Fedora).

Headers for the wrong Ruby version

A system-managed Ruby and a rbenv/asdf Ruby can diverge. mkmf looks under the active interpreter, so installing the distro ruby-dev may not match a hand-built Ruby.

How to fix it

Install the matching Ruby dev headers

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y ruby-dev
# RHEL/Fedora
dnf install -y ruby-devel

For rbenv/asdf Ruby, headers ship with the build

A Ruby installed via ruby-build already includes its headers. If mkmf cannot find them, you are likely shelling out to the system Ruby instead of the version-managed one.