Graalvm Native Image

GraalVM Native Image for Java Applications

Expert skill for building high-performance native executables from Java applications using GraalVM Native Image, dramatically reducing startup time and memory consumption.

Overview

GraalVM Native Image compiles Java applications ahead-of-time (AOT) into standalone native executables. These executables start in milliseconds, require significantly less memory than JVM-based deployments, and are ideal for serverless functions, CLI tools, and microservices where fast startup and low resource usage are critical.

This skill provides a structured workflow to migrate JVM applications to native binaries, covering build tool configuration, framework-specific patterns, reflection metadata management, and an iterative approach to resolving native build failures.

When to Use

Use this skill when:

• Converting a JVM-based Java application to a GraalVM native executable
• Optimizing cold start times for serverless or containerized deployments
• Reducing memory footprint (RSS) of Java microservices
• Configuring Maven or Gradle with GraalVM Native Build Tools
• Resolving ClassNotFoundException, NoSuchMethodException, or missing resource errors in native builds
• Generating or editing reflect-config.json, resource-config.json, or other GraalVM metadata files
• Using the GraalVM tracing agent to collect reachability metadata
• Implementing RuntimeHints for Spring Boot native support
• Building native images with Quarkus or Micronaut

Instructions

1. Contextual Project Analysis

Before any configuration, analyze the project to determine the build tool, framework, and dependencies:

Detect the build tool:

# Check for Maven
if [ -f "pom.xml" ]; then
    echo "Build tool: Maven"
    # Check for Maven wrapper
    [ -f "mvnw" ] && echo "Maven wrapper available"
fi

# Check for Gradle
if [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
    echo "Build tool: Gradle"
    [ -f "build.gradle.kts" ] && echo "Kotlin DSL"
    [ -f "gradlew" ] && echo "Gradle wrapper available"
fi

Detect the framework by analyzing dependencies:

• Spring Boot: Look for spring-boot-starter-* in pom.xml or build.gradle
• Quarkus: Look for quarkus-* dependencies
• Micronaut: Look for micronaut-* dependencies
• Plain Java: No framework dependencies detected

Check the Java version:

java -version 2>&1
# GraalVM Native Image requires Java 17+ (recommended: Java 21+)

Identify potential native image challenges:

• Reflection-heavy libraries (Jackson, Hibernate, JAXB)
• Dynamic proxy usage (JDK proxies, CGLIB)
• Resource bundles and classpath resources
• JNI or native library dependencies
• Serialization requirements

2. Build Tool Configuration

Configure the appropriate build tool plugin based on the detected environment.

For Maven projects, add a dedicated native profile to keep the standard build clean. See the Maven Native Profile Reference for full configuration.

Key Maven setup:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.10.6</version>
          <extensions>true</extensions>
          <executions>
            <execution>
              <id>build-native</id>
              <goals>
                <goal>compile-no-fork</goal>
              </goals>
              <phase>package</phase>
            </execution>
          </executions>
          <configuration>
            <imageName>${project.artifactId}</imageName>
            <buildArgs>
              <buildArg>--no-fallback</buildArg>
            </buildArgs>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Build with: ./mvnw -Pnative package

For Gradle projects, apply the org.graalvm.buildtools.native plugin. See the Gradle Native Plugin Reference for full configuration.

Key Gradle setup (Kotlin DSL):

plugins {
    id("org.graalvm.buildtools.native") version "0.10.6"
}

graalvmNative {
    binaries {
        named("main") {
            imageName.set(project.name)
            buildArgs.add("--no-fallback")
        }
    }
}

Build with: ./gradlew nativeCompile

3. Framework-Specific Configuration

Each framework has its own AOT strategy. Apply the correct configuration based on the detected framework.

Spring Boot (3.x+): Spring Boot has built-in GraalVM support with AOT processing. See the Spring Boot Native Reference for patterns including RuntimeHints, @RegisterReflectionForBinding, and test support.

Key points:

• Use spring-boot-starter-parent 3.x+ which includes the native profile
• Register reflection hints via RuntimeHintsRegistrar
• Run AOT processing with process-aot goal
• Build with: ./mvnw -Pnative native:compile or ./gradlew nativeCompile

Quarkus and Micronaut: These frameworks are designed native-first and require minimal additional configuration. See the Quarkus & Micronaut Reference.

4. GraalVM Reachability Metadata

Native Image uses a closed-world assumption — all code paths must be known at build time. Dynamic features like reflection, resources, and proxies require explicit metadata configuration.

Metadata files are placed in META-INF/native-image/<group.id>/<artifact.id>/:

See the Reflection & Resource Config Reference for complete format and examples.

5. The Iterative Fix Engine

Native image builds often fail due to missing metadata. Follow this iterative approach:

Step 1 — Execute the native build:

# Maven
./mvnw -Pnative package 2>&1 | tee native-build.log

# Gradle
./gradlew nativeCompile 2>&1 | tee native-build.log

Step 2 — Parse build errors and identify the root cause:

Common error patterns and their fixes:

Step 3 — Apply fixes by updating the appropriate metadata file or using framework annotations.

Step 4 — Rebuild and verify. Repeat until the build succeeds.

Step 5 — If manual fixes are insufficient, use the GraalVM tracing agent to collect reachability metadata automatically. See the Tracing Agent Reference.

6. Validation and Benchmarking

Once the native build succeeds:

Verify the executable runs correctly:

# Run the native executable
./target/<app-name>

# For Spring Boot, verify the application context loads
curl http://localhost:8080/actuator/health

Measure startup time:

# Time the startup
time ./target/<app-name>

# For Spring Boot, check the startup log
./target/<app-name> 2>&1 | grep "Started .* in"

Measure memory footprint (RSS):

# On Linux
ps -o rss,vsz,comm -p $(pgrep <app-name>)

# On macOS
ps -o rss,vsz,comm -p $(pgrep <app-name>)

Compare with JVM baseline:

7. Docker Integration

Build minimal container images with native executables:

# Multi-stage build
FROM ghcr.io/graalvm/native-image-community:21 AS builder
WORKDIR /app
COPY . .
RUN ./mvnw -Pnative package -DskipTests

# Minimal runtime image
FROM debian:bookworm-slim
COPY --from=builder /app/target/<app-name> /app/<app-name>
EXPOSE 8080
ENTRYPOINT ["/app/<app-name>"]

For Spring Boot applications, use paketobuildpacks/builder-jammy-tiny with Cloud Native Buildpacks:

./mvnw -Pnative spring-boot:build-image

Best Practices

1. Start with the tracing agent on complex projects to generate an initial metadata baseline 2. Use the `native` profile to keep native-specific config separate from standard builds 3. Prefer `--no-fallback` to ensure a true native build (no JVM fallback) 4. Test with `nativeTest` to run JUnit tests in native mode 5. Use GraalVM Reachability Metadata Repository for third-party library metadata 6. Minimize reflection — prefer constructor injection and compile-time DI where possible 7. Include resource patterns explicitly rather than relying on classpath scanning 8. Profile before and after — always measure startup and memory improvements 9. Use Java 21+ for the best GraalVM compatibility and performance 10. Keep GraalVM and Native Build Tools versions aligned

Examples

Example 1: Adding Native Support to a Spring Boot Maven Project

Scenario: You have a Spring Boot 3.x REST API and want to compile it to a native executable.

Step 1 — Add the native profile to `pom.xml`:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <executions>
            <execution>
              <id>process-aot</id>
              <goals>
                <goal>process-aot</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Step 2 — Register reflection hints for DTOs:

@RestController
@RegisterReflectionForBinding({UserDto.class, OrderDto.class})
public class UserController {

    @GetMapping("/users/{id}")
    public UserDto getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

Step 3 — Build and run:

./mvnw -Pnative native:compile
./target/myapp
# Started MyApplication in 0.089 seconds

Example 2: Resolving a Reflection Error in Native Build

Scenario: Native build fails with ClassNotFoundException for a Jackson-serialized DTO.

Error output:

com.oracle.svm.core.jdk.UnsupportedFeatureError:
  Reflection registration missing for class com.example.dto.PaymentResponse

Fix — Add to `src/main/resources/META-INF/native-image/reachability-metadata.json`:

{
  "reflection": [
    {
      "type": "com.example.dto.PaymentResponse",
      "allDeclaredConstructors": true,
      "allDeclaredMethods": true,
      "allDeclaredFields": true
    }
  ]
}

Or use the Spring Boot annotation approach:

@RegisterReflectionForBinding(PaymentResponse.class)
@Service
public class PaymentService { /* ... */ }

Example 3: Using the Tracing Agent for a Complex Project

Scenario: A project with many third-party libraries needs comprehensive reachability metadata.

# 1. Build the JAR
./mvnw package -DskipTests

# 2. Run with the tracing agent
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \
    -jar target/myapp.jar

# 3. Exercise all endpoints
curl http://localhost:8080/api/users
curl -X POST http://localhost:8080/api/orders -H 'Content-Type: application/json' -d '{"item":"test"}'
curl http://localhost:8080/actuator/health

# 4. Stop the application (Ctrl+C), then build native
./mvnw -Pnative native:compile

# 5. Verify
./target/myapp

Constraints and Warnings

Critical Constraints

• GraalVM Native Image requires Java 17+ (Java 21+ recommended for best compatibility)
• Closed-world assumption: All code paths must be known at build time — dynamic class loading, runtime bytecode generation, and MethodHandles.Lookup may not work
• Build time and memory: Native compilation is resource-intensive — expect 2-10 minutes and 4-8 GB RAM for typical projects
• Not all libraries are compatible: Libraries relying heavily on reflection, dynamic proxies, or CGLIB may require extensive metadata configuration
• AOT profiles are fixed at build time: Spring Boot @Profile and @ConditionalOnProperty are evaluated during AOT processing, not at runtime

Common Pitfalls

• Forgetting `--no-fallback`: Without this flag, the build may silently produce a JVM fallback image instead of a true native executable
• Incomplete tracing agent coverage: The agent only captures code paths exercised during the run — ensure all features are tested
• Version mismatches: Keep GraalVM JDK, Native Build Tools plugin, and framework versions aligned to avoid incompatibilities
• Classpath differences: The classpath at AOT/build time must match runtime — adding/removing JARs after native compilation causes failures

Security Considerations

• Native executables are harder to decompile than JARs, but are not tamper-proof
• Ensure secrets are not embedded in the native image at build time
• Use environment variables or external config for sensitive data

Troubleshooting

Gradle GraalVM Native Build Tools Plugin

Complete Gradle configuration for building GraalVM native images using the Native Build Tools plugin.

Table of Contents

1. Plugin Setup 2. Configuration Options 3. Spring Boot Gradle Integration 4. Testing in Native Mode 5. Multi-Project Builds

---

Plugin Setup

Kotlin DSL (build.gradle.kts)

plugins {
    java
    id("org.graalvm.buildtools.native") version "0.10.6"
}

graalvmNative {
    binaries {
        named("main") {
            imageName.set(project.name)
            mainClass.set("com.example.Application")
            buildArgs.add("--no-fallback")
            buildArgs.add("-H:+ReportExceptionStackTraces")
            javaLauncher.set(javaToolchains.launcherFor {
                languageVersion.set(JavaLanguageVersion.of(21))
                vendor.set(JvmVendorSpec.matching("GraalVM"))
            })
        }
    }
}

Groovy DSL (build.gradle)

plugins {
    id 'java'
    id 'org.graalvm.buildtools.native' version '0.10.6'
}

graalvmNative {
    binaries {
        main {
            imageName = project.name
            mainClass = 'com.example.Application'
            buildArgs.add('--no-fallback')
            buildArgs.add('-H:+ReportExceptionStackTraces')
        }
    }
}

Build with:

./gradlew nativeCompile

The native executable is produced in build/native/nativeCompile/.

Configuration Options

Binary Configuration

graalvmNative {
    binaries {
        named("main") {
            imageName.set(project.name)
            mainClass.set("com.example.Application")

            // Build arguments
            buildArgs.addAll(
                "--no-fallback",
                "-H:+ReportExceptionStackTraces",
                "--enable-https",
                "-J-Xmx8g"
            )

            // Quick build mode (faster build, slower runtime — dev only)
            quickBuild.set(false)

            // Rich output during build
            richOutput.set(true)

            // Verbose output
            verbose.set(true)

            // Resource includes
            resources {
                autodetect()
                includedPatterns.add("application.*")
                includedPatterns.add("META-INF/.*")
            }
        }
    }

    // GraalVM metadata repository
    metadataRepository {
        enabled.set(true)
        version.set("0.3.14")
    }

    // Toolchain detection
    toolchainDetection.set(true)
}

Java Toolchain Configuration

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}

graalvmNative {
    binaries {
        named("main") {
            javaLauncher.set(javaToolchains.launcherFor {
                languageVersion.set(JavaLanguageVersion.of(21))
                vendor.set(JvmVendorSpec.matching("GraalVM Community"))
            })
        }
    }
}

Spring Boot Gradle Integration

For Spring Boot 3.x projects with Gradle:

plugins {
    java
    id("org.springframework.boot") version "3.4.1"
    id("io.spring.dependency-management") version "1.1.7"
    id("org.graalvm.buildtools.native") version "0.10.6"
}

// Spring Boot plugin automatically configures AOT processing
// when GraalVM Native Image plugin is detected

Build commands:

# Compile to native executable
./gradlew nativeCompile

# Build OCI image with Cloud Native Buildpacks
./gradlew bootBuildImage

# Run the native executable
./build/native/nativeCompile/<app-name>

# Run AOT processing only
./gradlew processAot

Custom AOT Configuration

tasks.withType<org.springframework.boot.gradle.tasks.aot.ProcessAot>().configureEach {
    args("--spring.profiles.active=prod")
}

graalvmNative {
    binaries {
        named("main") {
            buildArgs.addAll(
                "--no-fallback",
                "-H:+ReportExceptionStackTraces"
            )
        }
    }
}

Testing in Native Mode

Run JUnit tests compiled as a native executable:

./gradlew nativeTest

Configure test binary:

graalvmNative {
    binaries {
        named("test") {
            buildArgs.addAll(
                "--no-fallback",
                "-H:+ReportExceptionStackTraces"
            )
        }
    }

    // Configure test support
    testSupport.set(true)
}

Multi-Project Builds

For multi-project Gradle builds, apply the plugin only in the executable subproject:

// settings.gradle.kts
pluginManagement {
    plugins {
        id("org.graalvm.buildtools.native") version "0.10.6"
    }
}

// app/build.gradle.kts (executable subproject)
plugins {
    id("org.graalvm.buildtools.native")
}

graalvmNative {
    binaries {
        named("main") {
            imageName.set("my-app")
            mainClass.set("com.example.Application")
        }
    }
}

Maven Native Build Tools Configuration

Complete Maven configuration for building GraalVM native images using the Native Build Tools plugin.

Table of Contents

1. Native Profile Setup 2. Plugin Configuration Options 3. Spring Boot Maven Integration 4. Testing in Native Mode 5. Multi-Module Projects

---

Native Profile Setup

Add a native profile to your pom.xml to keep native-specific configuration separate:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.10.6</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>
            <imageName>${project.artifactId}</imageName>
            <mainClass>${exec.mainClass}</mainClass>
            <buildArgs>
              <buildArg>--no-fallback</buildArg>
              <buildArg>-H:+ReportExceptionStackTraces</buildArg>
            </buildArgs>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Plugin Configuration Options

Common Build Arguments

<configuration>
  <imageName>${project.artifactId}</imageName>
  <mainClass>com.example.Application</mainClass>
  <fallback>false</fallback>
  <verbose>true</verbose>
  <buildArgs>
    <!-- Disable fallback to JVM -->
    <buildArg>--no-fallback</buildArg>
    <!-- Report exception stack traces -->
    <buildArg>-H:+ReportExceptionStackTraces</buildArg>
    <!-- Increase build memory -->
    <buildArg>-J-Xmx8g</buildArg>
    <!-- Enable HTTPS support -->
    <buildArg>--enable-https</buildArg>
    <!-- Quick build mode (dev only, slower runtime) -->
    <buildArg>-Ob</buildArg>
    <!-- Include all resources matching pattern -->
    <buildArg>-H:IncludeResources=application.*</buildArg>
  </buildArgs>
  <!-- GraalVM metadata repository support -->
  <metadataRepository>
    <enabled>true</enabled>
  </metadataRepository>
</configuration>

Metadata Repository Integration

The GraalVM Reachability Metadata Repository provides pre-built metadata for popular libraries:

<configuration>
  <metadataRepository>
    <enabled>true</enabled>
    <version>0.3.14</version>
  </metadataRepository>
</configuration>

Spring Boot Maven Integration

For Spring Boot 3.x projects, the parent POM includes a native profile. Combine with the Spring Boot Maven Plugin:

<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <executions>
            <execution>
              <id>process-aot</id>
              <goals>
                <goal>process-aot</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Build commands:

# Compile to native executable
./mvnw -Pnative native:compile

# Build OCI image with Cloud Native Buildpacks
./mvnw -Pnative spring-boot:build-image

# Run AOT processing only (for debugging)
./mvnw -Pnative process-aot

Testing in Native Mode

Run JUnit tests compiled as a native executable:

# Run native tests
./mvnw -Pnative test

# Or explicitly
./mvnw -Pnative native:test

Configure test-specific settings:

<execution>
  <id>test-native</id>
  <goals>
    <goal>test</goal>
  </goals>
  <phase>test</phase>
  <configuration>
    <buildArgs>
      <buildArg>-H:+ReportExceptionStackTraces</buildArg>
      <buildArg>--no-fallback</buildArg>
    </buildArgs>
  </configuration>
</execution>

Multi-Module Projects

For multi-module Maven projects, configure the native plugin in the module that produces the executable:

<!-- parent pom.xml -->
<pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.graalvm.buildtools</groupId>
      <artifactId>native-maven-plugin</artifactId>
      <version>0.10.6</version>
    </plugin>
  </plugins>
</pluginManagement>

<!-- child module pom.xml (the executable module) -->
<profiles>
  <profile>
    <id>native</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <configuration>
            <imageName>${project.artifactId}</imageName>
            <mainClass>com.example.Application</mainClass>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Quarkus & Micronaut Native Image Support

Configuration patterns for native-first Java frameworks with GraalVM Native Image.

Table of Contents

1. Quarkus Native Build 2. Quarkus Configuration 3. Micronaut Native Build 4. Micronaut Configuration 5. Comparison

---

Quarkus Native Build

Quarkus is designed native-first and requires minimal GraalVM-specific configuration.

Building a Native Executable

# Using Maven (Quarkus Maven plugin handles native build)
./mvnw package -Dnative

# Using Gradle
./gradlew build -Dquarkus.native.enabled=true

# Using Quarkus CLI
quarkus build --native

Container Build (no local GraalVM needed)

# Build in a container (uses Mandrel/GraalVM image)
./mvnw package -Dnative -Dquarkus.native.container-build=true

# Specify custom builder image
./mvnw package -Dnative \
    -Dquarkus.native.container-build=true \
    -Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21

Multi-Stage Dockerfile

FROM quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21 AS builder
COPY --chown=quarkus:quarkus mvnw /code/mvnw
COPY --chown=quarkus:quarkus .mvn /code/.mvn
COPY --chown=quarkus:quarkus pom.xml /code/
COPY --chown=quarkus:quarkus src /code/src
USER quarkus
WORKDIR /code
RUN ./mvnw package -Dnative -DskipTests

FROM quay.io/quarkus/quarkus-micro-image:2.0
WORKDIR /work/
COPY --from=builder /code/target/*-runner /work/application
RUN chmod 775 /work/application
EXPOSE 8080
CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

Quarkus Configuration

application.properties

# Native image build options
quarkus.native.additional-build-args=--no-fallback,-H:+ReportExceptionStackTraces

# Resource inclusion
quarkus.native.resources.includes=templates/**,META-INF/resources/**

# Enable HTTPS support
quarkus.native.enable-https-url-handler=true

# Build memory
quarkus.native.native-image-xmx=8g

Registering Reflection

Quarkus provides annotations to register classes for reflection:

import io.quarkus.runtime.annotations.RegisterForReflection;

@RegisterForReflection
public class MyDto {
    private String name;
    private int age;
    // constructors, getters, setters
}

// Register multiple classes including nested types
@RegisterForReflection(targets = {MyDto.class, OrderDto.class},
                       serialization = true)
public class ReflectionConfig {
}

Testing Native Builds

import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest
public class NativeMyResourceIT {

    @Test
    public void testHelloEndpoint() {
        given()
            .when().get("/hello")
            .then()
            .statusCode(200)
            .body(is("Hello"));
    }
}

Run native integration tests:

./mvnw verify -Dnative

---

Micronaut Native Build

Micronaut uses compile-time dependency injection and AOT processing, making it highly compatible with GraalVM.

Building a Native Executable

# Using Maven
./mvnw package -Dpackaging=native-image

# Using Gradle
./gradlew nativeCompile

# Using Micronaut CLI
mn create-app --build=gradle --jdk=21 --features=graalvm myapp

Gradle Configuration

plugins {
    id("io.micronaut.application") version "4.4.4"
    id("org.graalvm.buildtools.native") version "0.10.6"
}

micronaut {
    runtime("netty")
    testRuntime("junit5")
    processing {
        incremental(true)
        annotations("com.example.*")
    }
}

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

Maven Configuration

<plugin>
    <groupId>io.micronaut.maven</groupId>
    <artifactId>micronaut-maven-plugin</artifactId>
    <configuration>
        <configFile>aot-${packaging}.properties</configFile>
    </configuration>
</plugin>

<profiles>
    <profile>
        <id>native</id>
        <properties>
            <packaging>native-image</packaging>
            <micronaut.runtime>netty</micronaut.runtime>
        </properties>
    </profile>
</profiles>

Micronaut Configuration

Registering Reflection

Micronaut minimizes reflection, but when needed:

import io.micronaut.core.annotation.ReflectiveAccess;

@ReflectiveAccess
public class MyDto {
    private String name;
    private int age;
}

// Or use @Introspected for bean introspection (preferred)
import io.micronaut.core.annotation.Introspected;

@Introspected
public class MyDto {
    private String name;
    private int age;
}

Resource Inclusion

In src/main/resources/META-INF/native-image/resource-config.json:

{
  "resources": {
    "includes": [
      {"pattern": "application\\.yml"},
      {"pattern": "logback\\.xml"},
      {"pattern": "META-INF/.*"}
    ]
  }
}

Docker Build

# Using Micronaut Gradle plugin
./gradlew dockerBuildNative

# Multi-stage Dockerfile
FROM ghcr.io/graalvm/native-image-community:21 AS builder
WORKDIR /app
COPY . .
RUN ./gradlew nativeCompile --no-daemon

FROM debian:bookworm-slim
COPY --from=builder /app/build/native/nativeCompile/myapp /app/myapp
EXPOSE 8080
ENTRYPOINT ["/app/myapp"]

---

Comparison

GraalVM Reflection & Resource Configuration

Complete guide for GraalVM metadata files that enable reflection, resources, proxies, and serialization in native images.

Table of Contents

1. Configuration File Location 2. Unified Reachability Metadata 3. Reflection Configuration 4. Resource Configuration 5. Proxy Configuration 6. Serialization Configuration

---

Configuration File Location

Place metadata files in:

src/main/resources/
  META-INF/native-image/
    <group.id>/
      <artifact.id>/
        reachability-metadata.json    # Unified format (recommended)
        reflect-config.json           # Legacy: reflection only
        resource-config.json          # Legacy: resources only
        proxy-config.json             # Legacy: dynamic proxies
        serialization-config.json     # Legacy: serialization
        jni-config.json               # Legacy: JNI access
        native-image.properties       # Build arguments

GraalVM automatically discovers files in the META-INF/native-image/ directory.

Unified Reachability Metadata

The unified reachability-metadata.json format (recommended for GraalVM 23+) combines all metadata:

{
  "reflection": [
    {
      "type": "com.example.dto.UserDto",
      "allDeclaredConstructors": true,
      "allDeclaredMethods": true,
      "allDeclaredFields": true
    },
    {
      "condition": {
        "typeReached": "com.example.service.OrderService"
      },
      "type": "com.example.dto.OrderDto",
      "methods": [
        {"name": "<init>", "parameterTypes": []},
        {"name": "getId", "parameterTypes": []},
        {"name": "setId", "parameterTypes": ["java.lang.Long"]}
      ],
      "fields": [
        {"name": "id"},
        {"name": "status"}
      ]
    }
  ],
  "resources": [
    {"glob": "application.yml"},
    {"glob": "application-*.yml"},
    {"glob": "templates/**/*.html"},
    {"glob": "static/**"},
    {"glob": "META-INF/services/*"}
  ],
  "bundles": [
    {"name": "messages", "locales": ["en", "it", "de"]}
  ],
  "jni": [
    {
      "type": "com.example.NativeHelper",
      "methods": [
        {"name": "nativeMethod", "parameterTypes": ["int"]}
      ]
    }
  ]
}

Reflection Configuration

Legacy reflect-config.json

[
  {
    "name": "com.example.dto.UserDto",
    "allDeclaredConstructors": true,
    "allPublicConstructors": true,
    "allDeclaredMethods": true,
    "allPublicMethods": true,
    "allDeclaredFields": true,
    "allPublicFields": true
  },
  {
    "name": "com.example.dto.OrderDto",
    "methods": [
      {"name": "<init>", "parameterTypes": []},
      {"name": "<init>", "parameterTypes": ["java.lang.Long", "java.lang.String"]},
      {"name": "getId", "parameterTypes": []},
      {"name": "setId", "parameterTypes": ["java.lang.Long"]}
    ],
    "fields": [
      {"name": "id", "allowWrite": true},
      {"name": "status", "allowWrite": true}
    ]
  },
  {
    "name": "com.example.entity.Product",
    "allDeclaredConstructors": true,
    "allDeclaredMethods": true,
    "allDeclaredFields": true,
    "unsafeAllocated": true
  }
]

Common Reflection Flags

Resource Configuration

Legacy resource-config.json

{
  "resources": {
    "includes": [
      {"pattern": "application\\.yml"},
      {"pattern": "application-.*\\.yml"},
      {"pattern": "logback\\.xml"},
      {"pattern": "logback-spring\\.xml"},
      {"pattern": "META-INF/services/.*"},
      {"pattern": "templates/.*\\.html"},
      {"pattern": "static/.*"},
      {"pattern": "db/migration/.*\\.sql"}
    ],
    "excludes": [
      {"pattern": ".*\\.DS_Store"}
    ]
  },
  "bundles": [
    {"name": "messages", "locales": ["en", "it"]},
    {"name": "ValidationMessages"}
  ]
}

Proxy Configuration

Legacy proxy-config.json

Register interfaces for JDK dynamic proxy generation:

[
  {
    "interfaces": [
      "com.example.service.UserService",
      "org.springframework.aop.SpringProxy",
      "org.springframework.aop.framework.Advised",
      "org.springframework.core.DecoratingProxy"
    ]
  },
  {
    "interfaces": [
      "com.example.repository.OrderRepository",
      "org.springframework.data.repository.Repository"
    ]
  }
]

Serialization Configuration

Legacy serialization-config.json

{
  "types": [
    {"name": "com.example.dto.UserDto"},
    {"name": "com.example.dto.OrderDto"},
    {"name": "java.util.ArrayList"},
    {"name": "java.util.HashMap"}
  ],
  "lambdaCapturingTypes": [
    {"name": "com.example.service.UserService"}
  ]
}

native-image.properties

Configure default build arguments:

Args = --no-fallback \
       -H:+ReportExceptionStackTraces \
       --enable-https \
       --initialize-at-build-time=org.slf4j

Spring Boot Native Image Support

Complete guide for building Spring Boot 3.x applications as GraalVM native images with AOT processing.

Table of Contents

1. Prerequisites 2. AOT Processing 3. RuntimeHints Registration 4. Common Annotations 5. Conditional Beans in Native 6. Testing Native Applications 7. Cloud Native Buildpacks

---

Prerequisites

• Spring Boot 3.0+ (recommended: 3.4+)
• GraalVM JDK 21+ or GraalVM CE with native-image installed
• Native Build Tools plugin (Maven or Gradle)

Spring Boot 3.x provides first-class GraalVM Native Image support. The spring-boot-starter-parent includes a native profile with all necessary configurations.

AOT Processing

Spring Boot AOT processing generates optimized code at build time that replaces runtime reflection:

What AOT does:

• Evaluates @Conditional annotations at build time
• Generates bean definitions as source code
• Creates reflection hints for the remaining dynamic access
• Pre-computes component scanning and auto-configuration

Important constraints:

• Bean definitions must be fixed at build time
• @Profile conditions are evaluated during AOT — active profiles must be specified at build time
• @ConditionalOnProperty is evaluated at build time
• Classpath must remain the same between AOT processing and runtime

Configuring Active Profiles at Build Time

<!-- Maven -->
<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>process-aot</id>
            <configuration>
                <profiles>prod</profiles>
            </configuration>
        </execution>
    </executions>
</plugin>

// Gradle
tasks.withType<org.springframework.boot.gradle.tasks.aot.ProcessAot>().configureEach {
    args("--spring.profiles.active=prod")
}

RuntimeHints Registration

When Spring Boot's automatic hint detection is insufficient, register hints manually:

Using RuntimeHintsRegistrar

import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;
import org.springframework.context.annotation.ImportRuntimeHints;

@ImportRuntimeHints(MyRuntimeHints.class)
@Configuration
public class AppConfig {
    // ...
}

public class MyRuntimeHints implements RuntimeHintsRegistrar {

    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        // Register reflection
        hints.reflection()
            .registerType(MyDto.class,
                builder -> builder
                    .withMembers(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS,
                                 MemberCategory.INVOKE_DECLARED_METHODS,
                                 MemberCategory.DECLARED_FIELDS));

        // Register resources
        hints.resources()
            .registerPattern("templates/*.html")
            .registerPattern("static/**");

        // Register serialization
        hints.serialization()
            .registerType(MySerializableClass.class);

        // Register proxies
        hints.proxies()
            .registerJdkProxy(MyInterface.class);
    }
}

Using @RegisterReflectionForBinding

A convenience annotation to register reflection hints for DTOs and data classes:

@RestController
@RegisterReflectionForBinding({UserDto.class, OrderDto.class, AddressDto.class})
public class UserController {

    @GetMapping("/users/{id}")
    public UserDto getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

Using @Reflective

Mark individual classes for reflection registration:

@Reflective
public class MyDto {
    private String name;
    private int age;
    // getters, setters, constructors
}

Common Annotations

Conditional Beans in Native

Beans using @Conditional annotations are evaluated at build time during AOT:

// This works — condition is resolved at build time
@Configuration
@Profile("prod")
public class ProdConfig {
    @Bean
    public DataSource dataSource() { /* ... */ }
}

// This requires the property to be available at build time
@Configuration
@ConditionalOnProperty(name = "feature.enabled", havingValue = "true")
public class FeatureConfig {
    @Bean
    public FeatureService featureService() { /* ... */ }
}

Best practice: For native images, prefer environment variables over properties for runtime-switchable configuration.

Testing Native Applications

Native Test Execution

Run JUnit tests in native mode to verify AOT-compiled tests:

# Maven
./mvnw -Pnative test

# Gradle
./gradlew nativeTest

Test-Specific AOT Processing

# Maven
./mvnw -Pnative spring-boot:process-test-aot

# Gradle
./gradlew processTestAot

RuntimeHints Testing

Verify that runtime hints are correctly registered without building a native image:

import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.predicate.RuntimeHintsPredicates;

@Test
void shouldRegisterHints() {
    RuntimeHints hints = new RuntimeHints();
    new MyRuntimeHints().registerHints(hints, getClass().getClassLoader());

    assertThat(RuntimeHintsPredicates.reflection()
        .onType(MyDto.class)
        .withMemberCategories(MemberCategory.INVOKE_DECLARED_CONSTRUCTORS))
        .accepts(hints);

    assertThat(RuntimeHintsPredicates.resource()
        .forResource("templates/index.html"))
        .accepts(hints);
}

Cloud Native Buildpacks

Build OCI images with Paketo Buildpacks (no local GraalVM installation needed):

# Maven
./mvnw -Pnative spring-boot:build-image \
    -Dspring-boot.build-image.imageName=myapp:native

# Gradle
./gradlew bootBuildImage \
    --imageName=myapp:native

Configure the builder in pom.xml:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <image>
            <builder>paketobuildpacks/builder-jammy-tiny:latest</builder>
            <env>
                <BP_NATIVE_IMAGE>true</BP_NATIVE_IMAGE>
                <BP_NATIVE_IMAGE_BUILD_ARGUMENTS>
                    --no-fallback -H:+ReportExceptionStackTraces
                </BP_NATIVE_IMAGE_BUILD_ARGUMENTS>
            </env>
        </image>
    </configuration>
</plugin>

GraalVM Tracing Agent

Guide for using the GraalVM tracing agent to automatically collect reachability metadata for native image builds.

Table of Contents

1. Overview 2. Running the Tracing Agent 3. Agent Modes 4. Integration with Build Tools 5. Filtering and Fine-Tuning

---

Overview

The GraalVM tracing agent intercepts all dynamic accesses (reflection, resources, JNI, proxies, serialization) during application execution on the JVM and generates the corresponding GraalVM metadata files.

When to use the tracing agent:

• Initial native image migration of a complex project
• After adding new libraries with reflection requirements
• When manual metadata configuration is insufficient
• To discover hidden reflection/resource usage

Important: The agent only captures code paths exercised during the run. Ensure thorough coverage by running all application features, endpoints, and edge cases.

Running the Tracing Agent

Basic Usage

# Create output directory
mkdir -p src/main/resources/META-INF/native-image

# Run with the tracing agent
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \
    -jar target/myapp.jar

Then exercise all application features (call APIs, trigger scheduled tasks, etc.) before shutting down gracefully.

With Spring Boot

# Run Spring Boot app with tracing agent
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \
    -jar target/myapp.jar

# Exercise all endpoints
curl http://localhost:8080/api/users
curl -X POST http://localhost:8080/api/users -H 'Content-Type: application/json' -d '{"name":"test"}'
curl http://localhost:8080/actuator/health

# Shut down gracefully (Ctrl+C or kill -SIGTERM)

Merging with Existing Config

# Merge agent output with existing metadata (does not overwrite)
java -agentlib:native-image-agent=config-merge-dir=src/main/resources/META-INF/native-image \
    -jar target/myapp.jar

Agent Modes

Output Mode (Fresh Config)

Writes new configuration, overwriting any existing files:

-agentlib:native-image-agent=config-output-dir=<path>

Merge Mode (Append to Existing)

Merges new entries into existing configuration files:

-agentlib:native-image-agent=config-merge-dir=<path>

Conditional Mode

Generate conditional metadata (only include if a type is reachable):

-agentlib:native-image-agent=config-output-dir=<path>,experimental-conditional-config-filter-file=filter.json

Integration with Build Tools

Maven — Run Agent During Tests

<profiles>
  <profile>
    <id>agent</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <configuration>
            <agent>
              <enabled>true</enabled>
              <options>
                <option>config-output-dir=src/main/resources/META-INF/native-image</option>
              </options>
            </agent>
          </configuration>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-surefire-plugin</artifactId>
          <configuration>
            <argLine>-agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image</argLine>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

Run with:

./mvnw -Pagent test

Gradle — Run Agent During Tests

graalvmNative {
    agent {
        defaultMode.set("standard")
        metadataCopy {
            inputTaskNames.add("test")
            outputDirectories.add("src/main/resources/META-INF/native-image")
            mergeWithExisting.set(true)
        }
    }
}

Run with:

# Run tests with agent
./gradlew -Pagent test

# Copy collected metadata
./gradlew metadataCopy

Filtering and Fine-Tuning

Agent Filter Configuration

Create a filter file to reduce noise in the generated metadata:

{
  "rules": [
    {
      "excludeClasses": "jdk.internal.**"
    },
    {
      "excludeClasses": "sun.**"
    },
    {
      "excludeClasses": "com.sun.**"
    },
    {
      "includeClasses": "com.example.**"
    }
  ]
}

Use with:

java -agentlib:native-image-agent=config-output-dir=<path>,caller-filter-file=filter.json \
    -jar target/myapp.jar

Post-Processing Agent Output

After collecting metadata, review and clean up:

1. Remove unnecessary entries — The agent is conservative; many entries may not be needed 2. Add conditions — Use condition.typeReached to limit when metadata is applied 3. Verify correctness — Build the native image and test thoroughly 4. Commit metadata — Add the generated files to version control

Recommended Workflow

# 1. Run agent with tests for baseline coverage
./mvnw -Pagent test

# 2. Run agent with the full application for runtime coverage
java -agentlib:native-image-agent=config-merge-dir=src/main/resources/META-INF/native-image \
    -jar target/myapp.jar
# Exercise all features, then shut down

# 3. Build native image
./mvnw -Pnative package

# 4. Test the native executable
./target/myapp

# 5. If failures occur, repeat steps 2-4 with additional code paths