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:

```xml
<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
```bash
./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) |