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

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:

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:

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):

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:

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:

Measure startup time:

Measure memory footprint (RSS):

Compare with JVM baseline:

7. Docker Integration

Build minimal container images with native executables:

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

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:

Step 2 — Register reflection hints for DTOs:

Step 3 — Build and run:

Example 2: Resolving a Reflection Error in Native Build

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

Error output:

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

Or use the Spring Boot annotation approach:

Example 3: Using the Tracing Agent for a Complex Project

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

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