Maven GraalVM "native-image building failed" - Fix Native Build in CI

By Daniel Zoghalchali·Latchkey

A GraalVM native-image build failed. The common causes are missing reachability metadata (reflection, resources, proxies discovered only at runtime), a missing native build toolchain (a C compiler/linker the image build shells out to), or the image build running out of memory - native-image is very memory-hungry.

What this error means

The native:compile goal fails with Native Image building failed, often preceded by an analysis error like ClassNotFoundException during reflection, Error: Image build request failed, a missing gcc/cl.exe, or an OutOfMemoryError in the builder.

mvn output

[ERROR] Failed to execute goal org.graalvm.buildtools:native-maven-plugin:0.10.2:compile
(build-native) on project app: 'native-image' building failed.
Error: Classes that should be initialized at run time got initialized during
image building ...  / Error: Image build request failed with exit status 137

Common causes

Missing reachability metadata

Reflection, resource loading, dynamic proxies, and JNI that native-image cannot see statically need explicit metadata (reflect-config.json etc.). Without it the build fails or the binary breaks at runtime.

Missing native toolchain or out-of-memory

native-image shells out to a C compiler/linker; without gcc/build-essential (or MSVC on Windows) it cannot link. The analysis/compile phase is also memory-heavy and gets OOM-killed (exit 137) on small runners.

How to fix it

Provide GraalVM, a C toolchain, and metadata

Set up a GraalVM JDK with native-image and the C build tools, and add the reachability metadata repository.

.github/workflows/ci.yml

- uses: graalvm/setup-graalvm@v1
  with:
    java-version: '21'
    distribution: 'graalvm'
    native-image-job-reports: 'true'
- run: sudo apt-get install -y build-essential   # gcc/linker for native-image
- run: mvn -B -Pnative native:compile

Give the builder more memory (or a bigger runner)

native-image needs a lot of RAM; cap or raise it and use a larger runner to avoid OOM (exit 137).

pom.xml (native-maven-plugin)

<configuration>
  <buildArgs>
    <buildArg>-J-Xmx6g</buildArg>
    <buildArg>--no-fallback</buildArg>
  </buildArgs>
</configuration>

How to prevent it

Generate/maintain reachability metadata (run the tracing agent against your tests).
Provision GraalVM + a C toolchain in CI and assert native-image --version.
Build native images on a runner with enough RAM, or cap -J-Xmx to fit.

Frequently asked questions

What causes ""Native Image building failed""?

Reflection, resource loading, dynamic proxies, and JNI that native-image cannot see statically need explicit metadata (reflect-config.json etc.). Without it the build fails or the binary breaks at runtime.

How do I fix "Native Image building failed"?