Reachability Metadata for Maven

Use this guide to resolve native-image build failures caused by missing reachability metadata for reflection, resources, serialization, or JNI. Follow the workflow below to detect, collect, and manually add metadata as needed.

Detect Missing Metadata

Add these options to your Maven plugin configuration to enable metadata checks and warnings:

<configuration>
  <buildArgs>
    <buildArg>--exact-reachability-metadata</buildArg>
  </buildArgs>
  <runtimeArgs>
    <runtimeArg>-XX:MissingRegistrationReportingMode=Warn</runtimeArg>
  </runtimeArgs>
</configuration>

Resolution Workflow

Run the Tracing Agent

Run the tracing agent to collect metadata:

./mvnw -Pnative -Dagent=true test
./mvnw -Pnative native:metadata-copy
./mvnw -Pnative package

Configure metadata copy in your plugin:

<agent>
  <enabled>true</enabled>
  <metadataCopy>
    <disabledStages>
      <stage>main</stage>
    </disabledStages>
    <merge>true</merge>
    <outputDirectory>META-INF/native-image</outputDirectory>
  </metadataCopy>
</agent>

Add Manual Metadata if Needed

If the agent-collected metadata is incomplete, add manual configuration:

Create META-INF/native-image/<project-groupId>/manual-metadata/ and add a reachability-metadata.json file containing only the sections you need. Native Image automatically picks up metadata from this location.

For metadata layout and file semantics, see the Reachability Metadata documentation.

Minimal reachability-metadata.json reflection example:

{
  "reflection": [
    {
      "condition": {
        "typeReached": "com.example.Condition"
      },
      "type": "com.example.Type",
      "methods": [
        {
          "name": "<init>",
          "parameterTypes": []
        }
      ]
    }
  ]
}

Rebuild and Verify

Rebuild and test your project:

./mvnw -Pnative package
./mvnw -Pnative test

If a library still fails after repository, agent, and manual entries, capture the exact missing symbol from the error output and add only that entry.

2.1 KiB Raw Blame History