Why Doesn’t Reflection Work in GraalVM’s Native Image?

1. How Reflection Works in Traditional JVMs

In a traditional JVM, reflection allows the application to:
✅ Discover and inspect classes, methods, and fields at runtime
✅ Dynamically instantiate objects and invoke methods
✅ Access private members using reflection APIs

Example of reflection in Java:

import java.lang.reflect.Method;

class Test {
    public void hello() {
        System.out.println("Hello, Reflection!");
    }
}

public class ReflectionExample {
    public static void main(String[] args) throws Exception {
        Class<?> clazz = Class.forName("Test");
        Object obj = clazz.getDeclaredConstructor().newInstance();
        Method method = clazz.getMethod("hello");
        method.invoke(obj);  // Output: Hello, Reflection!
    }
}

Why This Works in a Traditional JVM

• The JVM loads classes dynamically at runtime.
• It can resolve method names, fields, and classes on the fly.
• Bytecode remains available throughout execution.

---

2. Why Reflection Fails in GraalVM Native Image

GraalVM Native Image mode compiles Java AOT (Ahead-of-Time) into a native executable.
This means:

• No dynamic class loading at runtime 📌
• Only classes known at compile time are included 📌
• No metadata for classes, methods, or fields unless explicitly registered 📌

What Happens When Using Reflection in Native Image?

If you run the previous reflection code in a GraalVM Native Image, it will fail with an exception like:

java.lang.ClassNotFoundException: Test

This is because:

• The Test class was not explicitly marked for inclusion.
• Native Image removes unused classes and methods for optimization.
• Reflection depends on metadata that doesn’t exist in the compiled binary.

---

3. Workarounds: How to Use Reflection in GraalVM Native Image

GraalVM allows limited reflection if you explicitly declare which classes and methods should be retained.

Solution 1: Reflection Configuration Files

You need to tell GraalVM which classes will be used reflectively by using a JSON configuration file.

Example reflect-config.json:

[
  {
    "name": "Test",
    "allDeclaredMethods": true,
    "allDeclaredConstructors": true
  }
]

Then, pass it when building the native image:

native-image --initialize-at-build-time --reflect-config=reflect-config.json -jar myapp.jar

Solution 2: GraalVM Reflection Annotations

Instead of a JSON file, you can use GraalVM annotations to keep metadata:

import com.oracle.svm.core.annotate.*;

@ReflectiveAccess
class Test {
    public void hello() {
        System.out.println("Hello, Reflection!");
    }
}

With this annotation, GraalVM will retain the class metadata.