GraalVM Native Image with Spring Boot 3: AOT Compilation Guide

Spring Boot 3 brought a paradigm shift with full support for GraalVM Native Image. After years of being a niche, experimental feature, native compilation is now production-ready — but only if you know the landmines. I've spent the last year migrating six microservices from JVM to native images at a payment processing company, and the results are staggering: sub-100ms startup times, memory usage dropping from 512MB to 64MB, and no more cold-start issues in Kubernetes. But the path is littered with pitfalls: reflection, proxies, serialization, and class initialization all behave differently. This guide covers everything from the basic setup to the gory details of AOT (Ahead-of-Time) compilation, real production incidents, and debugging techniques that the official docs gloss over. If you're running Spring Boot 3.2+ and want to deploy to serverless or containerized environments, this is your roadmap. Expect to break things, learn the hard way, and come out with a faster, leaner application.

Setting Up GraalVM Native Image with Spring Boot 3

Start by installing GraalVM JDK. I recommend GraalVM for JDK 21 (21.0.2) as it has the best performance and compatibility with Spring Boot 3.3+. Set JAVA_HOME to the GraalVM installation and ensure 'native-image' tool is installed via 'gu install native-image'. For Maven, add the spring-boot-maven-plugin with the native profile and the org.graalvm.buildtools:native-maven-plugin. The key dependency is spring-boot-starter-parent 3.3.0 which includes AOT processing out of the box. Build the native image with 'mvn -Pnative native:compile'. Expect the first build to take 3-5 minutes on a modern machine — AOT analysis is heavy. The resulting binary will be in target/<app-name>. Run it directly: ./target/myapp. You'll see startup times under 200ms even for complex apps.

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

<profiles>
    <profile>
        <id>native</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.graalvm.buildtools</groupId>
                    <artifactId>native-maven-plugin</artifactId>
                </plugin>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <configuration>
                        <image>
                            <builder>paketobuildpacks/builder:tiny</builder>
                        </image>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

What the Official Docs Won't Tell You

Spring Boot's documentation is good, but it hides the dirty reality: AOT compilation is a closed-world optimization. Any dynamic behavior — reflection, proxies, serialization, resource loading — must be declared at build time. The official docs tell you to use @RegisterReflectionForBinding, but they don't tell you that every library you use (Thymeleaf, Hibernate, even Spring Security) may have its own hidden reflection. I once spent two days debugging a NoSuchMethodError because CGLIB proxies were not registered. Another thing: the native-maven-plugin's default configuration is too permissive — it includes all classes from the classpath, which bloats the binary. Use the 'buildArgs' to exclude unnecessary packages. Also, don't expect all Spring Boot starters to work. For example, spring-boot-starter-actuator with info endpoints that use reflection will fail. You need to explicitly register each endpoint's metadata. The bottom line: run with the tracing agent during integration tests and inspect the generated 'reflect-config.json' — that's your true friend.

[
  {
    "name":"com.example.payment.dto.PaymentRequest",
    "allDeclaredFields":true,
    "allDeclaredMethods":true,
    "allDeclaredConstructors":true
  },
  {
    "name":"com.example.payment.dto.PaymentResponse",
    "allDeclaredFields":true,
    "allDeclaredMethods":true,
    "allDeclaredConstructors":true
  }
]

Configuring AOT Processing: Maven vs Gradle

Both Maven and Gradle support AOT processing, but the configuration differs. For Maven, the spring-boot-maven-plugin with the 'native' profile triggers AOT processing automatically. You can customize AOT options via the 'aot' configuration: 'aotJvmArgs', 'aotMainClass', etc. For Gradle, use the 'org.graalvm.buildtools.native' plugin and the 'bootBuildImage' task. The Gradle approach is more flexible for multi-module projects but requires more boilerplate. One critical setting: set 'spring.aot.enabled=true' in your application.properties for local testing. This enables AOT processing at runtime for development, which helps catch missing hints early. Also, configure 'spring.aot.jvm-args' to pass additional arguments. I've found that Maven is simpler for single-module apps, while Gradle is better for complex builds. But beware: Gradle's incremental compilation can cause stale AOT artifacts — always run clean build.

spring.aot.enabled=true
spring.aot.jvm-args=-Dspring.aot.debug=true
# Enable to see AOT processing logs
logging.level.org.springframework.aot=DEBUG

Handling Reflection and Dynamic Proxies

Reflection is the number one cause of native image failures. Spring Boot uses reflection heavily for dependency injection, property binding, and serialization. The AOT engine tries to analyze your code statically, but it can't see classes loaded via Class.forName() or dynamic proxies. For Jackson, every DTO that gets serialized/deserialized must be registered. Use @RegisterReflectionForBinding on a configuration class. For CGLIB proxies (e.g., @Configuration classes with @Bean methods), Spring Boot 3 automatically generates AOT proxies, but if you use custom interfaces with dynamic proxies, you must register them via the 'proxy-config.json' file. Similarly, for Hibernate, all entity classes must be registered for reflection. The safest approach is to run the tracing agent with your full test suite and merge the generated config. But be careful: the agent may generate duplicates or miss classes that are only loaded in certain code paths. I recommend manually reviewing the 'reflect-config.json' and adding any missing classes.

import org.springframework.aot.hint.annotation.RegisterReflectionForBinding;

@Configuration
@RegisterReflectionForBinding({PaymentRequest.class, PaymentResponse.class, RefundRequest.class})
public class PaymentConfig {
    
    @Bean
    public ObjectMapper objectMapper() {
        return new ObjectMapper();
    }
}

Optimizing Binary Size and Startup Time

A default native image for a Spring Boot app can be 50-100MB. That's huge for a container. You can reduce it significantly with build-time options. First, use the '--enable-url-protocols=http' only if needed — don't include all protocols. Second, use '--initialize-at-build-time' for packages that don't need runtime initialization. Third, exclude unused classes with '--exclude-config' and '--exclude-classes'. For example, if you don't use Thymeleaf, exclude its classes. Fourth, use the '--gc=serial' garbage collector for minimal memory overhead. Finally, use the 'paketobuildpacks/builder:tiny' base image which strips out unnecessary OS packages. With these optimizations, I've reduced binary size from 80MB to 25MB and startup time from 150ms to 80ms. But be careful: aggressive exclusions can break functionality. Always test thoroughly.

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <configuration>
        <buildArgs>
            <buildArg>--gc=serial</buildArg>
            <buildArg>--enable-url-protocols=http</buildArg>
            <buildArg>--initialize-at-build-time=com.example</buildArg>
            <buildArg>--exclude-classes=org.thymeleaf.**</buildArg>
            <buildArg>--exclude-config=/dev/null,/dev/null</buildArg>
        </buildArgs>
    </configuration>
</plugin>

Testing Native Images: Integration and CI/CD

Testing native images is non-negotiable. You can't just run JVM tests and assume they'll pass in native mode. Use Spring Boot's @SpringBootTest with the 'native' profile: set 'spring.aot.enabled=true' in your test properties. But more importantly, run a dedicated native test suite using the 'native-maven-plugin' with the 'test' goal: 'mvn -Pnative test'. This compiles a test native image and runs all tests. This is slow (5-10 minutes) but catches 90% of reflection issues. For CI/CD, I recommend a pipeline with three stages: (1) JVM unit tests for speed, (2) native test compilation and execution, (3) native image build and deployment. Use GitHub Actions or Jenkins with a dedicated GraalVM runner. Also, use Testcontainers for integration tests with databases — they work fine with native images if you register the JDBC driver reflection hints. One gotcha: Mockito doesn't work in native images because of dynamic proxies. Use manual mocks or switch to a different mocking library.

@SpringBootTest
@ActiveProfiles("native")
class PaymentServiceNativeTest {

    @Autowired
    private PaymentService paymentService;

    @Test
    void shouldProcessPayment() {
        PaymentRequest request = new PaymentRequest("123", 100.0);
        PaymentResponse response = paymentService.process(request);
        assertNotNull(response);
        assertEquals("SUCCESS", response.getStatus());
    }
}

Debugging Native Image Failures

When a native image fails, the error messages are cryptic: 'com.oracle.svm.core.jdk.UnsupportedFeatureError: Proxy class defined by interfaces' or 'ClassNotFoundException' for classes that exist. The first step is to enable verbose logging with '--verbose' in buildArgs. This shows which classes are being analyzed. Second, use the '--trace-class-initialization' and '--trace-object-instantiation' flags to see why a class is being loaded. Third, inspect the generated 'reachability-metadata.json' to see what's included. Fourth, if you get a runtime error, run the native image with '-Dspring.aot.debug=true' to get more AOT logs. For segmentation faults, use GDB or the GraalVM diagnostic tools. I once had a segfault because of a native library (JNI) that wasn't compiled for the target architecture. The fix was to rebuild the JNI library with the correct flags. Another common issue: class initialization order. Use '--initialize-at-run-time' for problematic classes like Logback or HikariCP.

<buildArgs>
    <buildArg>--verbose</buildArg>
    <buildArg>--trace-class-initialization=com.example.payment</buildArg>
    <buildArg>--trace-object-instantiation=com.example.payment.PaymentService</buildArg>
    <buildArg>--initialize-at-run-time=ch.qos.logback.core,java.util.TimeZone</buildArg>
</buildArgs>

Production Deployment and Monitoring

Deploying a native image to production is straightforward: build the binary, put it in a Docker container (or run directly on the host), and deploy. But monitoring is different. JVM tools like VisualVM, JMX, and heap dumps don't work. You need to use OS-level tools: 'top', 'perf', 'strace'. For memory profiling, use GraalVM's '--monitor' flag which provides a built-in HTTP server for metrics. For logging, ensure your application logs to stdout/stderr — traditional file appenders may not work well. Use Spring Boot Actuator with native-friendly endpoints (exclude info and health endpoints that use reflection). Also, configure health checks to be lightweight: avoid database connections in health checks if possible. For crash recovery, native images exit with a signal on unhandled exceptions — use a process manager like systemd or Kubernetes liveness probes to restart. One critical point: native images don't support JVM flags like -Xmx. Memory is fixed at build time. Test memory usage under load before deploying.

FROM scratch
COPY target/myapp /app
EXPOSE 8080
ENTRYPOINT ["/app", \"--server.port=8080\"]
# Use scratch for minimal image size
# No shell, no packages — just the binary