What is GraalVM Native Image, how does it change the memory/startup model, and when do you use it?

• Ahead-of-time compilation – the Graal compiler compiles all reachable code to native machine code at build time, producing a standalone executable.
• SubstrateVM – a minimal embedded runtime bundled in the binary, providing GC, thread scheduling, and exception handling.
• Closed-world assumption – the universe of code is fixed at build time; anything not statically reachable is discarded.
• Reflection hints – JSON configuration files listing classes and members used via reflection, dynamic proxies, JNI, and resources.
• Serial GC – the default collector in the community edition, suited for small heaps typical of serverless and CLI workloads.
• Trade-off – millisecond startup and low memory vs. longer build times, lower peak throughput than a warmed JVM, and framework compatibility work.

What is GraalVM Native Image?

GraalVM Native Image is an ahead-of-time compilation technology that turns a Java application into a standalone native executable. The build process starts with a static reachability analysis: starting from your main method, the tool computes every class, method, and field that could be reached. Unreachable code is discarded. The reachable code is compiled to native machine code.

# Build a native image from a jar
native-image -jar balance-service.jar -o balance-service

# Run it: starts in milliseconds
./balance-service

How does the closed-world assumption work?

The closed-world assumption means the entire universe of code is fixed and fully known at build time. This enables aggressive dead-code elimination and optimization, but it clashes with Java's dynamic features.

package com.bank.service;

import java.math.BigDecimal;

public class BalanceService {
    // This works in native image: fully static
    public BigDecimal getBalance(String accountId) {
        return new BigDecimal("50000.00");
    }

    // This breaks without a reflection hint:
    // Class.forName("com.bank.model.Account")
    // The static analysis cannot see the class name is a string
}

What are reflection hints and why are they needed?

Reflection that looks up a class or method by a string name cannot be discovered by static analysis. You must provide configuration hints, typically JSON files.

[
  {
    "name": "com.bank.model.Account",
    "allDeclaredConstructors": true,
    "allPublicMethods": true,
    "allDeclaredFields": true
  },
  {
    "name": "com.bank.model.TransferReceipt",
    "allDeclaredConstructors": true,
    "allPublicMethods": true
  }
]

# Place hint files in META-INF/native-image/
src/main/resources/META-INF/native-image/
  reflect-config.json
  resource-config.json
  proxy-config.json

Modern frameworks automate this. Spring Boot's AOT processing, Quarkus, and Micronaut precompute reflection hints at build time. The tracing agent can also generate hints by observing a running application.

# Generate hints automatically with the tracing agent
java -agentlib:native-image-agent=config-output-dir=hints \
     -jar balance-service.jar

# Then build with the generated hints
native-image -jar balance-service.jar \
     -H:ConfigurationFileDirectories=hints

How does the startup and memory model change?

The standard JVM loads classes, interprets bytecode, and JIT-compiles hot methods over time. This gives excellent peak throughput after warmup but slow startup and high memory.

Native Image inverts this. Because the binary is already machine code with its runtime baked in, there is no class loading, no interpretation, and no JIT warmup.

| Metric | Standard JVM | Native Image |
|--------|-------------|---------------|
| Startup | Seconds | Milliseconds |
| Memory (RSS) | 200-500 MB | 30-80 MB |
| Peak throughput | Highest (after warmup) | Lower (no runtime profiling) |
| Build time | Fast (javac) | Slow (minutes) |
| Dynamic features | Full support | Requires hints |

package com.bank.service;

public class StartupDemo {
    public static void main(String[] args) {
        long start = System.nanoTime();
        System.out.println("Balance service started in " +
            (System.nanoTime() - start) / 1_000_000 + " ms");
    }
}

# On JVM:
Balance service started in 1200 ms

# As native image:
Balance service started in 12 ms

What is SubstrateVM?

SubstrateVM is the minimal runtime embedded in the native binary. It provides:

• Garbage collector – Serial GC by default (community edition); G1 available in Oracle GraalVM.
• Thread scheduling – managed by the runtime.
• Exception handling – stack unwinding compiled in.

There is no bytecode interpreter and no JIT compiler in the image.

When should you use native image?

Use native image when startup and memory dominate cost:

• Serverless functions – billed per invocation and per MB; millisecond cold start saves real money.
• CLI tools – must feel instant to the user.
• Scale-to-zero microservices – fast scaling up and down.
• Container-dense deployments – low per-instance memory.

When should you stay on the JVM?

Stay on the JVM when:

• Peak throughput matters for long-running services; the JIT compiler with runtime profiling outperforms AOT.
• Heavy reflection without native support; debugging hint misses is painful.
• Fast iterative builds – native builds take minutes vs. seconds for javac.
• Operational maturity – JVM tooling (JFR, JMX, async profilers) is more mature.

What are the common pitfalls?

The most common pitfall is a reflective mapper or serializer failing at runtime because a hint was missing. Always test thoroughly.

// This works on JVM but fails in native image without hints:
ObjectMapper mapper = new ObjectMapper();
Account account = mapper.readValue(json, Account.class);
// Fix: register Account in reflect-config.json

Build times are long (minutes), so develop on the JVM for fast iteration and build native images in CI.

What about Spring Boot and Quarkus?

Spring Boot 3+ supports native image with AOT processing. Quarkus was designed for native image from the start.

# Spring Boot native build
./mvnw -Pnative native:compile

# Quarkus native build
./mvnw package -Dnative

What should a senior engineer know?

Many teams do both: JVM in development for speed of iteration, native image in production for deployment benefits. Profile-guided optimization can narrow the peak-throughput gap. The Foreign Function and Memory API works well with native image because it is designed for AOT compatibility. Expect native-image support to improve as frameworks and the GraalVM team collaborate on reducing hint requirements.