Generate reflection metadata for GraalVM Native Image

In this guide, you will see several methods to provide the metadata required for reflection to be used in a Micronaut application distributed as a GraalVM Native executable.

Authors: Sergio del Amo

Micronaut Version: 4.5.0

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

In this tutorial, you are going to learn how to use Reflection in Native Image within a Micronaut application.

Java reflection support (the java.lang.reflect.* API) enables Java code to examine its own classes, methods, fields and their properties at run time.

Native Image supports reflection but needs to know ahead-of-time the reflectively accessed program elements.

Micronaut Framework internals do not use reflection. However, you may want to use reflection in your application or use a Java library that uses reflection.

This tutorial will create a Micronaut application that uses reflection, and then show different techniques to configure it to work with Native Image.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Create the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

5. Reflection Example

5.1. Classes

Create two classes to transform a java.lang.String. You will invoke them via Java Reflection.

package example.micronaut;

public class StringReverser {

    static String reverse(String input) {
        return new StringBuilder(input).reverse().toString();
package example.micronaut;

public class StringCapitalizer {

    static String capitalize(String input) {
        return input.toUpperCase();

5.2. Singleton

Create a singleton class that transform a java.lang.String via reflection.

package example.micronaut;

import jakarta.inject.Singleton;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;

@Singleton (1)
public class StringTransformer {

    private static final Logger LOG = LoggerFactory.getLogger(StringTransformer.class);

    String transform(String input, String className, String methodName) {
        try {
            Class<?> clazz = Class.forName(className);
            Method method = clazz.getDeclaredMethod(methodName, String.class);
            return method.invoke(null, input).toString();
        } catch (ClassNotFoundException e) {
            LOG.error("Class not found: {}", className);
            return input;
        } catch (NoSuchMethodException e) {
            LOG.error("Method not found: {}", methodName);
            return input;
        } catch (InvocationTargetException e) {
            LOG.error("InvocationTargetException: {}", e.getMessage());
            return input;
        } catch (IllegalAccessException e) {
            LOG.error("IllegalAccessException: {}", e.getMessage());
            return input;
1 Use jakarta.inject.Singleton to designate a class as a singleton.

5.3. Controller

Create a controller, which exposes two routes, and calls the StringTransformer passing it a class name and method name.

package example.micronaut;

import io.micronaut.core.annotation.Nullable;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;
import io.micronaut.http.annotation.QueryValue;

@Controller("/transformer") (1)
public class StringTransformerController {

    private final StringTransformer transformer;

    public StringTransformerController(StringTransformer transformer) {  (2)
        this.transformer = transformer;

    @Produces(MediaType.TEXT_PLAIN) (3)
    @Get("/capitalize{?q}") (4)
    String capitalize(@Nullable @QueryValue String q) { (5)
        String className = "example.micronaut.StringCapitalizer";
        String methodName = "capitalize";
        return transformer.transform(q, className, methodName);

    @Produces(MediaType.TEXT_PLAIN) (3)
    @Get("/reverse{?q}") (4)
    String reverse(@Nullable @QueryValue String q) { (5)
        String className = "example.micronaut.StringReverser";
        String methodName = "reverse";
        return transformer.transform(q, className, methodName);
1 The class is defined as a controller with the @Controller annotation mapped to the path /transformer.
2 Use constructor injection to inject a bean of type StringTransformer.
3 Set the response content-type to text/plain with the @Produces annotation.
4 Use the @QueryValue annotation to define the q to be provided in the query part of the URL. Micronaut will parse them from request and provide as arguments to the method.

6. Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

You can execute the endpoint exposed by application:

curl "localhost:8080/transformer/capitalize?q=Hello"

As expected, the output is:


7. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, the polyglot embeddable virtual machine, to generate a native executable of our Micronaut application.

Compiling native executables ahead of time with GraalVM improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

7.1. GraalVM installation

The easiest way to install GraalVM on Linux or Mac is to use

Java 17
sdk install java 17.0.8-graal
Java 17
sdk use java 17.0.8-graal

For installation on Windows, or for manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 17
sdk install java 17.0.8-graalce
Java 17
sdk use java 17.0.8-graalce

7.2. Native executable generation

To generate a native executable using Maven, run:

./mvnw package -Dpackaging=native-image

The native executable is created in the target directory and can be run with target/micronautguide.

8. Invoke the Native Image

You can execute the endpoint exposed by the native executable:

curl "localhost:8080/transformer/capitalize?q=Hello"

Transformation does not work the native executable. The response is Hello instead of the expected HELLO.

You will see an ERROR log in the native image execution logs:

 ERROR example.micronaut.StringTransformer - Class not found: example.micronaut.StringCapitalizer

In the next sections, you wil provide the necessary reflection metadata.

8.1. Tests

Write a test which should pass both for JIT or Native Image.

package example.micronaut;

import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.BlockingHttpClient;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.http.uri.UriBuilder;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;


import static org.junit.jupiter.api.Assertions.*;

@MicronautTest (1)
class StringTransformerControllerTest {

    void capitalize(@Client("/") HttpClient httpClient) { (2)
        BlockingHttpClient client = httpClient.toBlocking();
        URI uri = uri("capitalize");
        assertEquals("HELLO", client.retrieve(HttpRequest.GET(uri)));

    void reverse(@Client("/") HttpClient httpClient) { (2)
        BlockingHttpClient client = httpClient.toBlocking();
        URI uri = uri("reverse");
        assertEquals("olleh", client.retrieve(HttpRequest.GET(uri)));

    private URI uri(String path) {
        return UriBuilder.of("/transformer") (3)
                .queryParam("q", "hello")
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Inject the HttpClient bean and point it to the embedded server.
3 UriBuilder API allows you to create a easily.

9. Testing the Application

To run the tests:

./mvnw test

10. Native Tests

This plugin supports running tests on the JUnit Platform as native images. This means that tests will be compiled and executed as native code.

First, add the following profile to pom.xml:


Then, to execute the native tests, execute:

./mvnw -Pnative test

INFO: A test may be disabled within a GraalVM native image via the @DisabledInNativeImage annotation.

10.1. Test Failures

Test will fail you will see something like:

 JUnit Jupiter:StringTransformerControllerTest:reverse(HttpClient)
    MethodSource [className = 'example.micronaut.StringTransformerControllerTest', methodName = 'reverse', methodParameterTypes = 'io.micronaut.http.client.HttpClient']
    => org.opentest4j.AssertionFailedError: expected: <olleh> but was: <hello>

Test run finished after 74 ms
[         3 containers found      ]
[         0 containers skipped    ]
[         3 containers started    ]
[         0 containers aborted    ]
[         3 containers successful ]
[         0 containers failed     ]
[         3 tests found           ]
[         0 tests skipped         ]
[         3 tests started         ]
[         0 tests aborted         ]
[         1 tests successful      ]
[         2 tests failed          ]

FAILURE: Build failed with an exception.

11. Handling Reflection

You can use Reflection in Native Image. GraalVM analysis attempts to automatic detection of reflection usages. If automatic analysis fails, you can provide manually the program elements reflectively accessed at run time.

You will see learn how to do this several ways with Micronaut Framework

11.1. Generating Reflection Metadata with GraalVM Tracing Agent

GraalVM provides a Tracing Agent to easily gather metadata and prepare configuration files.

It is possible to run tests with the agent.

mvn -Pnative -Dagent=true test

When the agent system property is set to true (or when the agent is enabled in the POM), the agent will be automatically attached to your Maven Surefire test execution, and the generated files can be found in the target/native/agent-output/test directory.

11.2. reflect-config.json

Reflection metadata can be provided to the native-image builder by providing JSON files stored in the META-INF/native-image/<>/<> project directory.

Create a new file src/main/resources/META-INF/native-image/example.micronaut.micronautguide/reflect-config.json:

    "methods":[{"name":"capitalize","parameterTypes":["java.lang.String"] }]
    "methods":[{"name":"reverse","parameterTypes":["java.lang.String"] }]

If you execute the Native Tests again, they will pass.

11.3. @ReflectionConfig

Delete the JSON file you created in the previous step. Replace it with a class with @ReflectConfig annotations.

package example.micronaut;

import io.micronaut.core.annotation.ReflectionConfig;

        type = StringReverser.class,
        methods = {
                @ReflectionConfig.ReflectiveMethodConfig(name = "reverse", parameterTypes = {String.class})
        type = StringCapitalizer.class,
        methods = {
                @ReflectionConfig.ReflectiveMethodConfig(name = "capitalize", parameterTypes = {String.class})
class GraalConfig {
1 @ReflectionConfig is a repeatable annotation that directly models the GraalVM reflection config JSON format.

The Micronaut GraalVM Annotation processor visits the annotation and provides the reflection metadata with a GraalVM Feature.

<!-- Add the following to your annotationProcessorPaths element -->

Micronaut Parent POM defines the micronaut-graal processor. You don’t need to specify it in your application’s pom.xml.

If you execute the Native Tests again, they will pass.

11.4. @ReflectiveAccess

If you can access the code, as in this example, you can annotate the class or method being accessed with reflection with @ReflectiveAccess.

Delete the GraalConfig class and annotate StringReverser and StringCapitalizer methods with @ReflectiveAccess.

package example.micronaut;

import io.micronaut.core.annotation.ReflectiveAccess;

public class StringReverser {

    @ReflectiveAccess (1)
    static String reverse(String input) {
        return new StringBuilder(input).reverse().toString();
package example.micronaut;

import io.micronaut.core.annotation.ReflectiveAccess;

public class StringCapitalizer {

    @ReflectiveAccess (1)
    static String capitalize(String input) {
        return input.toUpperCase();
1 @ReflectiveAccess annotation that can be declared on a specific type, constructor, method or field to enable reflective access just for the annotated element.

If you execute the Native Tests again, they will pass.

12. Next steps

Learn more about:

12.2. GraalVM Cloud deployment Guides

13. Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

14. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).