Ruby mini_racer / libv8 Build Fails in CI

mini_racer embeds V8 via the libv8-node gem. Building V8 from source is enormous, so it relies on a precompiled libv8 platform gem - when the platform is not locked or a C++ toolchain is missing, the build fails.

What this error means

bundle install fails on mini_racer or libv8-node, reporting that a compatible libv8 could not be found for the platform, or a C++ compile error. It frequently appears when the Linux platform is missing from the lockfile.

An error occurred while installing libv8-node (...), and Bundler cannot continue.

ERROR: could not find a precompiled libv8-node for your platform
(x86_64-linux). Building from source is not supported.

Common causes

No precompiled libv8 for the locked platform

libv8-node ships precompiled per platform. If x86_64-linux is missing from PLATFORMS, Bundler cannot find a matching V8 build and the install fails.

Missing C++ toolchain for mini_racer’s extension

mini_racer still compiles a thin C++ binding against libv8. Without g++/clang++ and the Ruby headers, that compile fails even when libv8 is present.

How to fix it

Lock the Linux platform for the precompiled libv8

Add the runner platform so Bundler selects the matching precompiled libv8-node.

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

Install the C++ toolchain and headers

# Debian/Ubuntu
apt-get update && apt-get install -y build-essential g++ python3 ruby-dev

How to prevent it

• Keep x86_64-linux (and -musl on Alpine) in Gemfile.lock so precompiled libv8 is used.
• Pin mini_racer/libv8-node versions known to ship a build for your platform.
• Bake g++, python3, and ruby-dev into images that build mini_racer.

Related guides