Gradle GraalVM nativeCompile Failure - Fix Native Build in CI

By Daniel Zoghalchali·Latchkey

A GraalVM nativeCompile (via the org.graalvm.buildtools.native plugin) failed. As on Maven, the causes are missing reachability metadata (reflection/resources/proxies), a missing native build toolchain (C compiler/linker), or the memory-hungry image build getting OOM-killed.

What this error means

The nativeCompile task fails with native-image building failed, an analysis error (Classes that should be initialized at run time got initialized during image building), a missing gcc/linker, or exit status 137 (OOM) from the builder.

gradle output

> Task :app:nativeCompile FAILED
Error: Image build request failed with exit status 1
com.oracle.svm.core.util.UserError$UserException: Classes that should be
initialized at run time got initialized during image building

Common causes

Missing reachability metadata

Reflection, resources, dynamic proxies, and JNI not visible to static analysis need explicit metadata, or the build fails / the binary breaks at runtime.

Missing C toolchain or out-of-memory

native-image needs a C compiler/linker to produce the binary; without it linking fails. The build is also memory-heavy and gets OOM-killed (exit 137) on small runners.

How to fix it

Provision GraalVM, a C toolchain, and run nativeCompile

Set up a GraalVM JDK with native-image plus the C build tools.

.github/workflows/ci.yml

- uses: graalvm/setup-graalvm@v1
  with:
    java-version: '21'
    distribution: 'graalvm'
- run: sudo apt-get install -y build-essential
- run: ./gradlew nativeCompile

Configure build args and give the builder memory

Add metadata/build args and raise the builder heap (or use a bigger runner) to avoid OOM.

build.gradle.kts

graalvmNative {
    binaries {
        named("main") {
            buildArgs.add("--no-fallback")
            buildArgs.add("-J-Xmx6g")
        }
    }
}

How to prevent it

Maintain reachability metadata (run the tracing agent against tests).
Provision GraalVM + a C toolchain in CI and assert native-image --version.
Run nativeCompile on a runner with enough RAM, or cap -J-Xmx.

Frequently asked questions

What causes ""native-image building failed" (Gradle)"?