Ruby ffi Gem Build Fails - Missing libffi in CI

The ffi gem builds a native extension when no precompiled gem matches the platform, and that build needs libffi plus a compiler. Missing those, or a platform not locked, fails the install.

What this error means

bundle install fails with "An error occurred while installing ffi", and the build log references libffi or a missing compiler. On a locked platform the precompiled gem installs with no compiling.

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

checking for ffi.h... no
checking for ffi_call() in -lffi... no
*** extconf.rb failed ***

Common causes

libffi development files not installed

A source build of ffi needs libffi-dev (ffi.h and libffi). On a slim image those headers are absent, so extconf fails.

Linux platform not locked, forcing a source build

Without x86_64-linux in PLATFORMS, Bundler will not select ffi’s precompiled gem and falls back to compiling from source.

How to fix it

Use the precompiled platform gem

Lock the Linux platform so Bundler picks ffi’s prebuilt gem and skips compiling.

bundle lock --add-platform x86_64-linux
bundle install

Install libffi and the toolchain for a source build

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

How to prevent it

• Keep x86_64-linux in Gemfile.lock so the precompiled ffi is used.
• Bake libffi-dev and build-essential into images that compile ffi.
• Pin ffi to a version that publishes precompiled platform builds.

Related guides