Traditional Java applications running on the Java Virtual Machine (JVM) offer high peak throughput, but they carry notable trade-offs: slow startup times and significant baseline memory consumption. In enterprise environments running microservices, containerized workloads on Kubernetes, or serverless functions on AWS Lambda, every megabyte of RAM and every millisecond of cold-start delay directly impacts operational costs and system elasticity. GraalVM Native Image paired with Spring Boot 4 provides an architectural solution to these operational challenges. By compiling Spring Boot applications ahead-of-time (AOT) into standalone native machine binaries, teams achieve sub-second startup times and 60 to 80 percent reductions in memory consumption.

Spring Boot 4 treats native compilation as a foundational, first-class capability rather than an experimental add-on. Its built-in AOT engine analyzes application configurations, pre-computes bean definitions, and generates explicit reachability metadata. In this comprehensive technical guide, you will learn how GraalVM Native Image works internally, how to build and containerize native Spring Boot 4 microservices, how to configure custom reflection hints with the RuntimeHints API, and how to make informed architectural decisions between native binaries and traditional JVM runtimes.

Article Navigation — Quick Index
What Is GraalVM Native Image? Why GraalVM Native Image Matters for Spring Boot 4 How Ahead-of-Time Compilation Works The Closed-World Assumption Spring Boot 4 AOT Processing Engine Step-by-Step Hands-On Tutorial: Building a Native Microservice Working with Reflection and RuntimeHints Unit Testing Runtime Hints with RuntimeHintsPredicates Cloud-Native Containerization & Distroless Packaging Architectural Comparison: Native Image vs. HotSpot vs. Leyden vs. CRaC Real-World Enterprise Use Cases Production Hardening Guidelines & Memory Sizing Common Pitfalls & Drop-In Fixes Frequently Asked Questions Authoritative Resources & Companion Code

Article Navigation — Quick Index

What Is GraalVM Native Image?

GraalVM is an advanced, high-performance polyglot runtime developed by Oracle. One of its core technologies is Native Image, which compiles Java bytecode ahead-of-time (AOT) into standalone native executables (such as Linux ELF, macOS Mach-O, or Windows PE binaries) for specific target operating systems and CPU architectures (x86_64 and aarch64).

In standard Java execution, the Java Virtual Machine starts by loading class files, interpreting bytecode, and using Just-in-Time (JIT) compilation (such as the HotSpot C1 and C2 compilers) to optimize frequently executed code paths during runtime. While this allows the JIT compiler to perform aggressive runtime profiling and speculative optimizations, it requires the JVM to load thousands of classes, manage dynamic class loaders, and run JIT compilation threads during application startup. This creates the classic Java “warm-up” delay and causes high baseline resident set size (RSS) memory consumption.

In contrast, GraalVM Native Image analyzes your application at compile time. It evaluates the entire call graph, discovers all reachable code paths, compiles them into native machine instructions, and stores initialized runtime data directly into a pre-populated Image Heap. The resulting native executable includes only the application code, its third-party library dependencies, and a stripped-down runtime called SubstrateVM.

Comparison diagram of Traditional JVM HotSpot versus GraalVM Native Image showing memory usage startup time and application binary differences — Figure 1: Traditional JVM HotSpot architecture compared with GraalVM Native Image: pre-compiled machine code delivers smaller memory footprints and sub-second startup times.

SubstrateVM acts as a lightweight runtime that provides essential operating system abstractions, memory management, garbage collection, and thread scheduling. Because SubstrateVM does not contain a bytecode interpreter or a dynamic JIT compiler, the resulting binary starts almost instantaneously and does not require an installed Java Development Kit or JRE on the host machine.

Why GraalVM Native Image Matters for Spring Boot 4

For many years, running enterprise Java in cloud environments involved distinct operational compromises. As organizations modernized their systems from monolithic architectures into distributed microservices and containerized topologies, the operational footprint of standard Java became apparent in four critical areas:

Serverless Cold Starts: On on-demand compute platforms such as AWS Lambda, Google Cloud Run, and Azure Container Apps, instances scale to zero during idle periods. When a new incoming HTTP request arrives, a standard JVM Spring Boot microservice often takes 3 to 8 seconds to initialize. A GraalVM native binary completes initialization in 50 to 180 milliseconds, virtually eliminating cold-start latency.
High Kubernetes Infrastructure Costs: In high-density Kubernetes worker nodes, each standard Spring Boot pod typically demands a minimum memory limit of 350 MB to 512 MB to accommodate the JVM heap, Metaspace, thread stacks, and JIT compiler code cache. A native executable operates comfortably within a 45 MB to 80 MB memory envelope. This memory reduction allows engineering teams to deploy 4 to 6 times more service instances on the same compute hardware.
Rapid Elastic Autoscaling (HPA): When traffic surges occur, Kubernetes Horizontal Pod Autoscalers (HPA) launch additional pod replicas. Because native binaries start and pass health readiness checks within milliseconds, they handle incoming traffic immediately without dropping requests or causing connection queuing.
Minimal Container Image Sizes: Standard JVM container images require a full Linux distribution and a JRE base image, often exceeding 250 MB to 400 MB in size. A native executable packaged inside a minimal Google Distroless or Alpine Linux image weighs between 50 MB and 80 MB, leading to faster container registry downloads, reduced network egress, and minimal vulnerability surface area.

If you are developing enterprise applications with Spring Boot 4, native image compilation provides a production-grade path toward cloud-native efficiency.

How Ahead-of-Time Compilation Works

To successfully build and deploy native applications, developers must understand the technical process that transforms dynamic Java code into a static machine binary.

Spring Boot 4 AOT Processing Engine and GraalVM Native Compilation Pipeline — Figure 2: The Spring Boot 4 Ahead-of-Time (AOT) engine translates application context and bean configurations into static reachability metadata for GraalVM SubstrateVM compilation.

The native compilation pipeline operates across two major sequential stages: Spring Boot AOT processing during the Maven/Gradle build phase, followed by GraalVM SubstrateVM static analysis and compilation.

The Closed-World Assumption

Traditional JVM execution relies on an open-world assumption. The runtime assumes that any class could be dynamically loaded at any moment using Class.forName(), custom class loaders, or network class downloading. Spring Boot traditionally took full advantage of this model: during startup, it scanned classpaths, searched for annotations using reflection, generated dynamic CGLIB proxies, and bound properties reflectively.

In contrast, GraalVM Native Image enforces the closed-world assumption. Under this rule, the compiler must know every single class, method, field, and resource that will ever be executed at build time. During static analysis:

Points-To Reachability Analysis: The compiler starts at the application’s entry point (the main(String[] args) method) and traces every reachable call path through the application and its dependencies.
Dead Code Elimination: Any class, interface, method, or dependency that is not reachable from the entry point is permanently removed from the compiled binary. If a third-party library contains 5,000 methods but your application only invokes 12 of them, the remaining 4,988 methods are discarded.
Build-Time Initialization & Image Heap: GraalVM initializes safe static classes and builds immutable object graphs at compile time. These initialized objects are written directly into the Image Heap of the binary. When the application launches, the operating system maps this image heap straight into virtual memory, allowing instantaneous state readiness.
Static Machine Code Generation: All reachable bytecodes are compiled directly into native assembly instructions optimized for the target CPU architecture.

Spring Boot 4 AOT Processing Engine

Because the closed-world assumption forbids dynamic class generation and unguided reflection, traditional Spring Boot 2.x and 3.x patterns required extensive manual configuration. In Spring Boot 4, the framework includes an integrated Spring AOT Engine that solves this challenge automatically.

During the build (invoked via the process-aot Maven goal), Spring Boot launches an ahead-of-time evaluation of your application. The AOT engine inspects all @Configuration classes, @RestController endpoints, Spring Data repositories, and @Service beans. Instead of deferring bean registration to runtime, it generates standard Java source code files that explicitly register bean definitions with the GenericApplicationContext using functional callbacks. Furthermore, it inspects your domain models, records, and DTOs to generate JSON reachability configurations for reflection, resource patterns, dynamic proxies, and Java serialization.

As a result, modern Spring Boot 4 microservices compile into native images out of the box with zero manual boilerplate for standard Spring idioms.

Step-by-Step Hands-On Tutorial: Building a Native Microservice

Let us walk through creating, building, and running a production-ready native Spring Boot 4 microservice step by step.

Step 1: Configure Maven Dependencies and Native Profiles

In Spring Boot 4.0.0, native compilation support is managed through the parent POM and the Spring Boot Maven plugin. Create a new project with the following pom.xml configuration:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.0.0</version>
        <relativePath/>
    </parent>

    <groupId>com.webcodein.nativedemo</groupId>
    <artifactId>native-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>native-demo</name>
    <description>GraalVM Native Image with Spring Boot 4 Demonstration</description>

    <properties>
        <java.version>25</java.version>
    </properties>

    <dependencies>
        <!-- Spring Web MVC Starter -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring Boot Actuator for Production Readiness Probes -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

        <!-- Spring Boot Test Starters -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Note that in Spring Boot 4, you do not declare the GraalVM native-maven-plugin in the top-level <plugins> block. The spring-boot-starter-parent automatically manages the GraalVM Native Build Tools under the predefined -Pnative profile.

Step 2: Implement the REST Endpoint and Application Entry Point

Create a standard Spring Boot application entry point and a REST controller that handles incoming HTTP requests. The controller returns a structured response demonstrating native execution:

package com.webcodein.nativedemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ImportRuntimeHints;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@SpringBootApplication
@ImportRuntimeHints(MyHints.class)
public class NativeDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(NativeDemoApplication.class, args);
    }
}

@RestController
class GreetingController {

    @GetMapping("/greet/{name}")
    public Map<String, Object> greet(@PathVariable String name) {
        return Map.of(
            "greeting", "Hello, " + name + "! Welcome to cloud-native Java.",
            "runtime", "GraalVM SubstrateVM Native Image",
            "framework", "Spring Boot 4.0.0",
            "javaVersion", System.getProperty("java.version"),
            "timestamp", System.currentTimeMillis()
        );
    }
}

Step 3: Compile to a Native Image

Developers have two distinct options for compiling the application into a native executable:

Option 1: Local Compilation via Native Build Tools

If you have GraalVM for JDK 25 installed and configured in your environment (with JAVA_HOME pointing to your GraalVM installation), run:

./mvnw -Pnative native:compile

This command instructs Maven to trigger the Spring AOT engine to generate reachability source code, then invokes GraalVM’s native-image compiler directly on your machine. The resulting standalone executable is generated in the target/ directory as target/native-demo (or target/native-demo.exe on Windows).

Option 2: Cloud Native Buildpacks (Zero GraalVM Installation Required)

If you do not want to install GraalVM locally, you can use Cloud Native Buildpacks. This approach uses Docker to spin up a standardized container environment (such as Paketo Buildpacks with BellSoft Liberica NIK) that performs the native build:

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

This command compiles your code, generates native reachability metadata, compiles the native executable inside the container, and outputs a production-ready OCI container image directly into your local Docker daemon.

Step 4: Verify Execution and Benchmark Startup Latency

Once compiled, execute the native binary and observe the startup metrics:

./target/native-demo

# Terminal Output:
#   .   ____          _            __ _ _
#  /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
# ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
#  \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
#   '  |____| .__|_| |_|_| |_\__, | / / / /
#  =========|_|==============|___/=/_/_/_/
#  :: Spring Boot ::                (v4.0.0)
#
# 2026-10-31T01:10:14.218Z  INFO 1420 --- [main] c.w.n.NativeDemoApplication : Started NativeDemoApplication in 0.169 seconds (process running for 0.174)

Now compare this native execution with traditional JVM execution using the executable JAR:

java -jar target/native-demo-0.0.1-SNAPSHOT.jar

# Terminal Output:
# 2026-10-31T01:10:32.451Z  INFO 1421 --- [main] c.w.n.NativeDemoApplication : Started NativeDemoApplication in 3.013 seconds (process running for 3.421)

The native image starts in 0.169 seconds compared to 3.013 seconds on the JVM — an improvement of roughly 18x faster startup speed. Under active load, the native binary uses approximately 54 MB of resident RAM compared to 310 MB on the JVM.

Working with Reflection and RuntimeHints

While the Spring Boot 4 AOT engine automatically registers all framework components, real-world enterprise applications frequently interact with dynamic classes, custom reflection, dynamic proxies, or dynamic classpath resources. Under GraalVM’s closed-world assumption, any class accessed via reflection that was not registered at compile time will throw a ClassNotFoundException or NoSuchMethodException at runtime.

GraalVM Closed World Analysis and Spring Boot 4 RuntimeHints Architecture — Figure 3: GraalVM closed-world static analysis blocks dynamic behavior unless bridged by Spring Boot 4 RuntimeHintsRegistrar metadata.

To bridge this boundary cleanly, Spring Boot 4 provides the RuntimeHintsRegistrar contract. This programmatic API allows developers to declare reflection, resource, serialization, and proxy requirements directly in Java code without writing manual JSON files.

Implementing a Custom RuntimeHintsRegistrar

Suppose our application includes a domain class MyDynamicClass that is instantiated dynamically via reflection based on incoming requests, along with a configuration file config/app.json located in src/main/resources/ that must be read at runtime.

First, inspect the target dynamic class:

package com.webcodein.nativedemo;

public class MyDynamicClass {

    private String status = "DYNAMIC_INITIALIZED";

    public MyDynamicClass() {
    }

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }
}

Next, implement the RuntimeHintsRegistrar interface to register both reflection capabilities and resource patterns:

package com.webcodein.nativedemo;

import org.springframework.aot.hint.MemberCategory;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;

public class MyHints implements RuntimeHintsRegistrar {

    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        // 1. Register reflection hints for dynamic class instantiation and method access
        hints.reflection().registerType(
            MyDynamicClass.class,
            builder -> builder.withMembers(
                MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS,
                MemberCategory.INVOKE_PUBLIC_METHODS,
                MemberCategory.DECLARED_FIELDS
            )
        );

        // 2. Register classpath resource patterns so GraalVM embeds them into the Image Heap
        hints.resources().registerPattern("config/*.json");
    }
}

Finally, link this registrar to your application using the @ImportRuntimeHints(MyHints.class) annotation on any @Configuration or @SpringBootApplication class.

Unit Testing Runtime Hints with RuntimeHintsPredicates

A major risk in native image development is discovering missing reflection hints late in your deployment pipeline after waiting 10 minutes for a native compile. Spring Boot provides RuntimeHintsPredicates to verify your hints during standard JVM unit tests in less than a second:

package com.webcodein.nativedemo;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.predicate.RuntimeHintsPredicates;

import static org.assertj.core.api.Assertions.assertThat;

class MyHintsTest {

    @Test
    @DisplayName("Should register reflection hints for MyDynamicClass constructors and methods")
    void shouldRegisterReflectionHints() {
        RuntimeHints hints = new RuntimeHints();
        new MyHints().registerHints(hints, getClass().getClassLoader());

        assertThat(RuntimeHintsPredicates.reflection().onType(MyDynamicClass.class))
            .accepts(hints);
    }

    @Test
    @DisplayName("Should register classpath resource hint for config/app.json")
    void shouldRegisterResourceHints() {
        RuntimeHints hints = new RuntimeHints();
        new MyHints().registerHints(hints, getClass().getClassLoader());

        assertThat(RuntimeHintsPredicates.resource().forResource("config/app.json"))
            .accepts(hints);
    }
}

By executing mvn test, these tests ensure that your reachability configuration is correct before submitting code to CI.

Cloud-Native Containerization & Distroless Packaging

Packaging native executables for containerized platforms requires understanding dynamic C runtime library dependencies. While a native image is a standalone binary, it links dynamically against the system C library (glibc or musl) and compression libraries such as zlib.

Cloud Native GraalVM Packaging with Buildpacks and Multi-Stage Docker to Kubernetes — Figure 4: Cloud-native packaging pathways: Cloud Native Buildpacks and multi-stage Docker builds deploying lightweight native containers to Kubernetes.

To create the smallest possible production image with the highest security posture, use a multi-stage Docker build targeting Google Container Tools’ distroless/base-debian12 image.

# Stage 1: Build the native binary using GraalVM community container
FROM ghcr.io/graalvm/native-image-community:25 AS builder
WORKDIR /workspace

# Cache Maven wrapper and dependencies
COPY .mvn/ .mvn/
COPY mvnw pom.xml ./
RUN ./mvnw dependency:go-offline -B -ntp

# Copy source code and compile native executable
COPY src/ src/
RUN ./mvnw -Pnative native:compile -DskipTests -B -ntp

# Stage 2: Minimal Distroless runtime image (no shell, no package managers)
FROM gcr.io/distroless/base-debian12:nonroot
WORKDIR /app

# CRITICAL FIX: The native binary links against zlib (libz.so.1).
# distroless/base does not include libz, which would trigger
# 'error while loading shared libraries: libz.so.1' on container startup.
COPY --from=builder /usr/lib64/libz.so.1 /lib/x86_64-linux-gnu/libz.so.1

# Copy the compiled standalone executable
COPY --from=builder /workspace/target/native-demo /app/native-demo

EXPOSE 8080
USER nonroot:nonroot

ENTRYPOINT ["/app/native-demo"]

This multi-stage build yields an image weighing roughly 65 MB. Running as nonroot without an interactive shell or package manager eliminates standard container attack vectors, making it ideal for strict enterprise compliance.

Architectural Comparison: Native Image vs. HotSpot vs. Leyden vs. CRaC

When selecting a runtime strategy for enterprise Java applications, architects must weigh startup latency, peak throughput, memory overhead, and development ergonomics across different Java execution technologies:

Architectural Dimension	GraalVM Native Image	Traditional JVM (HotSpot)	Project Leyden (JDK 25+)	CRaC (Coordinated Restore)
Startup Latency	0.05 – 0.20 seconds	2.5 – 8.0 seconds	0.5 – 1.2 seconds	0.02 – 0.05 seconds
Memory Consumption (RSS)	Ultra-Low (45 – 70 MB)	High (280 – 500+ MB)	Moderate (180 – 250 MB)	Moderate-High (JVM snapshot)
Peak Throughput	90 – 95% of JIT (Serial/G1 GC)	100% (Full JIT C2 profiling)	98 – 100% of JIT	100% (Warm JIT snapshot)
Build / Compilation Time	Slow (4 – 12 minutes)	Fast (10 – 30 seconds)	Fast-Moderate (1 – 2 minutes)	Fast build + Checkpoint phase
Dynamic Reflection Support	Requires explicit metadata hints	Full dynamic runtime support	Full dynamic runtime support	Full dynamic runtime support
Debugging & Profiling	GDB, JFR (JDK 25+)	Standard JDWP, JConsole, VisualVM	Standard JVM tooling	Standard JVM tooling
Target Workloads	Serverless, CLI, Edge, K8s Scale	Long-lived batch, large monoliths	General-purpose enterprise apps	AWS Lambda JVM snapstart

Real-World Enterprise Use Cases

GraalVM Native Image delivers compelling value in three distinct enterprise architectures:

1. Serverless & Event-Driven Microservices

In event-driven architectures utilizing AWS Lambda or Google Cloud Functions, services are charged per millisecond of compute time. Monolithic JVM applications often spend several seconds initializing framework contexts on cold start. By compiling Spring Boot 4 functions to GraalVM native binaries, cold-start latency drops below 200 milliseconds. This makes Java competitive with Go, Node.js, and Python in serverless environments while retaining the full Spring programming model.

2. High-Density Edge & IoT Gateways

In edge computing, industrial gateways, and smart retail devices, compute hardware operates with constrained RAM (such as 1 GB to 2 GB total system memory). Running multiple JVM microservices on an edge node is cost-prohibitive. Because a native Spring Boot service requires only 50 MB of RAM and no local JRE installation, multiple services can run concurrently on small hardware footprints.

3. Kubernetes Microservice Fleets with Aggressive Autoscaling

In high-traffic e-commerce and financial platforms experiencing rapid load spikes (such as flash sales or market openings), the Kubernetes Horizontal Pod Autoscaler needs to provision hundreds of new pod instances instantly. Traditional JVM applications often experience 503 Service Unavailable errors or gateway timeouts while waiting for new instances to complete JIT warm-up. Native Spring Boot images pass readiness checks immediately and handle full production traffic upon launch.

Architectural comparison of Kubernetes scale-to-zero pod lifecycles between Traditional JVM HotSpot and GraalVM Native Image illustrating boot stages, cold-start latency, memory RSS footprint, and pod density — Figure 5: Cloud-native elasticity in Kubernetes: traditional JVM cold-start latency (15-25s, 900MB RSS) versus GraalVM Native Image instant execution (35-50ms, 45MB RSS) enabling true scale-to-zero.

As illustrated in Figure 5, the architectural difference between the traditional JVM and GraalVM Native Image in cloud-native orchestrators is profound. A standard JVM pod requires 15 to 25 seconds of initialization overhead: the OS launches the heavy JVM process, scans the classpath, verifies bytecode, dynamically builds Spring application contexts, and executes interpretive JIT compilation loops. This latency causes severe cold-start penalties, causing Kubernetes HPA or KNative ingress routers to queue or drop incoming HTTP traffic. Furthermore, each JVM replica consumes 800 to 1,200 MB of Resident Set Size (RSS) memory, restricting a 16 GB Kubernetes worker node to roughly 12 to 14 active replicas.

In contrast, GraalVM Native Image compiles the entire Spring Boot 4 application ahead-of-time into an optimized Linux ELF machine binary. When traffic surges, the Linux kernel forks and executes the binary instantly. Pre-initialized heap memory structures load in 35 to 50 milliseconds, passing Kubernetes readiness probes on the very first cycle. Because baseline memory overhead drops to 35 to 55 MB RSS per replica, cluster operators achieve a 20-fold increase in pod density—packing upwards of 250 native replicas onto the same 16 GB worker node. This operational density enables true scale-to-zero serverless architectures, slashes cloud compute bills by over 80 percent, and pairs seamlessly with automated CI/CD deployment pipelines and local Testcontainers testing workflows.

Production Hardening Guidelines & Memory Sizing

Deploying native images to production Kubernetes clusters requires attention to operational tuning:

Garbage Collection Selection: By default, GraalVM Community Edition uses the Serial GC, which is optimized for small memory footprints and fast execution. For applications managing larger heaps (exceeding 4 GB) or requiring lower pause times, GraalVM Oracle/Enterprise Edition supports the production G1 GC. Configure memory limits explicitly using -Xmx (e.g., ENTRYPOINT ["/app/native-demo", "-Xmx128m"]).
Java Flight Recorder (JFR) Support: Since GraalVM for JDK 25, JFR is fully supported in native executables. You can monitor CPU utilization, thread contention, and heap allocations in production using standard JFR flags: -XX:+FlightRecorder -XX:StartFlightRecording=filename=recording.jfr.
Actuator Readiness and Liveness Probes: Native images initialize so quickly that external network proxies or database connection pools might not be ready when the HTTP server opens port 8080. Always configure Spring Boot Actuator probes (/actuator/health/readiness and /actuator/health/liveness) in your Kubernetes deployment manifests to coordinate traffic routing.
Combine with Virtual Threads: Spring Boot 4 supports Java 25 Virtual Threads in native mode. Add spring.threads.virtual.enabled=true to your application.properties to combine sub-millisecond native startup with high-throughput concurrent I/O.

Common Pitfalls & Drop-In Fixes

Pitfall 1: Missing Reflection Hints on Unregistered Libraries

Symptom: The application builds successfully, but throws java.lang.NoSuchMethodException or returns empty JSON objects during HTTP requests.

Root Cause: A third-party library or domain class uses reflection that was not detected by static analysis.

Fix: Implement a RuntimeHintsRegistrar and register all constructors and methods:

hints.reflection().registerType(
    TargetClass.class,
    builder -> builder.withMembers(
        MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS,
        MemberCategory.INVOKE_PUBLIC_METHODS
    )
);

Alternatively, use the GraalVM Reachability Metadata Repository by checking the official oracle/graalvm-reachability-metadata project on GitHub.

Pitfall 2: Missing Classpath Resources (Config, Schemas, Templates)

Symptom: The application throws java.io.FileNotFoundException or NullPointerException when calling classLoader.getResourceAsStream().

Root Cause: GraalVM strips non-class files from the image unless explicitly declared as resource patterns.

Fix: Register resource patterns in your RuntimeHintsRegistrar:

hints.resources().registerPattern("schemas/*.xsd");
hints.resources().registerPattern("templates/*.html");

Pitfall 3: Distroless Container Startup Failure (`libz.so.1`)

Symptom: Container crashes immediately upon startup with standard_init_linux.go: exec user process caused: no such file or directory or error while loading shared libraries: libz.so.1.

Root Cause: The compiled native binary dynamically links against zlib, which is not packaged in gcr.io/distroless/base.

Fix: Copy libz.so.1 directly from the builder stage in your multi-stage Dockerfile:

COPY --from=builder /usr/lib64/libz.so.1 /lib/x86_64-linux-gnu/libz.so.1

Frequently Asked Questions

Do I need to install GraalVM on my development machine to build native images?

No. By executing ./mvnw -Pnative spring-boot:build-image, Spring Boot uses Cloud Native Buildpacks to download a standardized builder container (such as Paketo Buildpacks with Liberica NIK) and compile your application inside Docker. You only need Docker installed and running locally.

Does Spring Data JPA and Hibernate work with GraalVM Native Image?

Yes. Spring Boot 4 and Hibernate 7.1 provide full AOT support. During build-time AOT processing, Hibernate pre-computes entity metamodels and proxy configurations, allowing standard JPA repositories and entities to compile into native binaries without manual reflection hints.

Can I use Spring Security with GraalVM Native Image?

Yes. Spring Security is fully compatible with Spring Boot 4 AOT compilation. Proxy generation for method security (such as @PreAuthorize) and security filter chains are pre-computed during the process-aot Maven phase.

Will GraalVM Native Image completely replace the traditional JVM?

No. Native Image and the JVM serve complementary roles. The traditional JVM remains ideal for long-running batch processing and large monolithic systems where peak throughput and dynamic profiling matter most. Native Image excels in containerized microservices, serverless functions, and autoscaling topologies where startup time and memory footprint are critical.

Why does native image compilation take 5 to 10 minutes?

Ahead-of-Time compilation performs whole-program points-to analysis, dead code elimination, and complex compiler optimizations for the target architecture that a JIT compiler usually spreads across hours of runtime. To optimize CI/CD pipelines, teams run standard JVM builds for feature branches and trigger native image builds only during deployment stages.

Authoritative Resources & Companion Code

Official Framework & Runtime Documentation:

Spring Boot GraalVM Native Image Support Reference — Official Spring guide to AOT processing, RuntimeHints, and container packaging.
GraalVM Native Image Reference Manual — Technical documentation for SubstrateVM, static analysis, and native-image flags.
Oracle GraalVM Reachability Metadata Repository — Centralized community repository of native configuration metadata for popular Java libraries.
OpenJDK Project Leyden — The standard OpenJDK project exploring ahead-of-time optimizations and class caching for HotSpot.

Companion Workshop Repository:

Full Companion Code on GitHub (workshop/cloud-native/graalvm-native-image-spring-boot) — Includes the working Spring Boot 4 service, RuntimeHints registrar, MockMvc tests, and multi-stage Dockerfile.

Related Cloud-Native & Architectural Guides:

All benchmark measurements and code samples in this article were verified using Java 25, Spring Boot 4.0.0, and GraalVM Native Image on Linux and Windows containers. Benchmark performance figures will vary based on hardware resources and microservice complexity.

Native Image

Posts

GraalVM Native Image with Spring Boot 4: A Practical Guide to Cloud-Native Java