Reachability Metadata for Gradle

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 Gradle configuration to enable metadata checks and warnings:

graalvmNative {
  binaries.all {
    buildArgs.add('--exact-reachability-metadata')
    runtimeArgs.add('-XX:MissingRegistrationReportingMode=Warn')
  }
}

Resolution Workflow

Run the Tracing Agent

Run the tracing agent to collect metadata:

./gradlew generateMetadata -Pcoordinates=<library-coordinates> -PagentAllowedPackages=<condition-packages>

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:

./gradlew nativeCompile
./gradlew nativeTest

1.6 KiB Raw Blame History