/build-native-image-maven

name: build-native-image-maven
description: Build GraalVM native images using the native-maven-plugin (org.graalvm.buildtools). Use this skill to build Java applications with Maven, configure pom.xml native image settings, run native tests, collect metadata, or resolve build or runtime issues.

Maven Native Image Build

Prerequisites

• Set `JAVA_HOME` to a GraalVM JDK installation so the plugin can find `native-image`.
• Do not require `GRAALVM_HOME` in the normal case. Only mention it if the user already relies on it or their environment needs an explicit override.
• Use Maven 3.6+.

Plugin Setup

Add the following to your `pom.xml` inside a `native` profile:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.11.1</version>
          <extensions>true</extensions>
          <executions>
            <execution>
              <id>build-native</id>
              <goals>
                <goal>compile-no-fork</goal>
              </goals>
              <phase>package</phase>
            </execution>
            <execution>
              <id>test-native</id>
              <goals>
                <goal>test</goal>
              </goals>
              <phase>test</phase>
            </execution>
          </executions>
          <configuration>
            <mainClass>org.example.Main</mainClass>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Build and Run

./mvnw -Pnative package                    # Build native image → target/<imageName>
./target/myapp                             # Run the native executable
./mvnw -Pnative test                       # Build and run JUnit tests as a native image
./mvnw -Pnative -DskipTests package        # Skip all tests
./mvnw -Pnative -DskipNativeTests package  # Run JVM tests only, skip native

Plugin Not Resolving or Activating

• **"Could not resolve artifact"** — Ensure `mavenCentral()` is in repositories and the version is correct.
• **"Could not find goal 'compile-no-fork'"** — Verify `<extensions>true</extensions>` is set on the plugin.
• **Build runs without native compilation** — Check you are activating the profile: `./mvnw -Pnative package`.

Build or Runtime Failures

For class initialization errors, linking issues, memory problems, or unexpected runtime behavior, see [references/maven-plugin-options.md](references/maven-plugin-options.md).

Missing Reachability Metadata

When native-image reports missing reflection, resources, serialization, or JNI entries, see [references/reachability-metadata.md](references/reachability-metadata.md).

Native Testing

For `nativeTest` failures or setting up native JUnit tests, see [references/testing.md](references/testing.md).

Reference Files

| Topic | File | |-------|------| | Plugin configuration options | [references/maven-plugin-options.md](references/maven-plugin-options.md) | | Missing reachability metadata | [references/reachability-metadata.md](references/reachability-metadata.md) | | Native testing | [references/testing.md](references/testing.md) |