Mastering GraalVM Native Image Reflection: The Ultimate Guide for Spring Boot 3

Why Reflection Configuration Is Needed

GraalVM cannot analyze reflective calls at compile time, so necessary metadata is missing at runtime, causing failures such as ClassNotFoundException for classes accessed via reflection.

Spring Boot 3 Reflection Configuration Mechanisms

Manual configuration (JSON) :

[
  {
    "name": "com.example.HiddenService",
    "methods": [{"name": "execute", "parameterTypes": []}]
  }
]

Automatic configuration using @RegisterReflectionForBinding:

@RestController
public class UserController {
  @PostMapping("/user")
  @RegisterReflectionForBinding(UserDTO.class)
  // auto‑generated reflection config
  public User createUser(@RequestBody UserDTO dto) {
    // ...
  }
}

Conditional configuration with @ConditionalOnNativeImage:

@Configuration
@ConditionalOnNativeImage
public class ReflectionConfig {
  @Bean
  public RuntimeHints hints() {
    return new RuntimeHints()
      .registerType(UserDTO.class, HintType.REFLECTION);
  }
}

Six Common Traps and Their Fixes

Trap 1: Third‑party library reflection calls – ClassNotFoundException for org.apache.commons.lang3.reflect.MethodUtils. Solution: register the type with @NativeHint.

@NativeHint(
  types = @TypeHint(types = MethodUtils.class)
)
public class CommonsLangHint implements RuntimeHintsRegistrar {
  // auto‑register
}

Trap 2: Missing dynamic‑proxy interfaces – NoClassDefFoundError for com.sun.proxy.$ProxyXX. Fix: register the proxy class via runtime hints.

@Configuration
public class ProxyConfig {
  @Bean
  RuntimeHints hints() {
    return new RuntimeHints()
      .proxies()
      .registerJdkProxy(MyService.class);
  }
}

Trap 3: Resource files not found – ResourceNotFoundException for messages.properties. Config:

@Bean
public RuntimeHints resourceHints() {
  return new RuntimeHints()
    .resources()
    .registerPattern("messages*.properties");
}

Trap 4: Insufficient JSON serialization support – InvalidTypeIdException during deserialization. Enhancement:

@NativeHint(
  types = @TypeHint(types = {UserDTO.class, PaymentInfo.class},
    typeNames = {"com.example._$HiddenClass"})
)

Trap 5: JNI call crashes – UnsatisfiedLinkError for native methods. Configuration: add --enable-jni to the native‑image command.

# native-image parameters
--enable-jni

Trap 6: Lambda expressions fail – LambdaConversionException. Root cure: explicitly register the generated lambda class.

// Explicitly register Lambda implementation
@TypeHint(types = UserService$$Lambda$0.class)

Ultimate Weapon: RuntimeHintsAgent

Collect runtime reflection data by running the application with the agent:

java -agentlib:native-image-agent=config-output-dir=META-INF/native-image \
     -jar application.jar

The agent automatically generates the necessary configuration files (shown in the following diagram).

Best‑Practice Checklist

1. Test‑driven configuration : cover all business scenarios with tests.

2. Layered configuration strategy :

src/main/resources/META-INF/native-image/
├── reflect-config.json
├── resource-config.json
└── jni-config.json

3. Continuous‑integration verification (GitHub Actions example):

# GitHub Actions
- name: Build Native Image
  run: ./mvnw -Pnative native:compile

Future: Configuration‑Free Native Compilation

The article demonstrates a complete workflow for handling reflection, resources, JNI, and lambda issues when building GraalVM native images for Spring Boot 3, enabling reliable production‑ready native binaries.