# Fix Missing Reachability Metadata

> Fix missing GraalVM reachability metadata for a specific library. Use when the user asks to fix or add metadata because required metadata is missing and tests or native-image runs fail with missing metadata errors.

- Skill: `oracle/fix-missing-reachability-metadata` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oracle/fix-missing-reachability-metadata`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oracle/fix-missing-reachability-metadata/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Oracle (https://skillmd.com/u/oracle)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/oracle/fix-missing-reachability-metadata

---


# Fix missing reachability metadata entries in the reachability-metadata.json

## Overview

Run a reproduce-fix-verify loop for missing metadata errors. Keep running the target test until it passes with no new missing metadata entries.

Library coordinates should be provided in the prompt in the format `group:artifact:version`. If you are not sure what the coordinates are, ask the user.

## Workflow

1. Reproduce the failure:
   - Run `./gradlew test -Pcoordinates=<coordinates>` from repository root.
2. Classify the failure:
   - If the failure is a `Missing*RegistrationError` or GraalVM reports matching metadata that is inactive because its condition was not satisfied, continue with metadata repair.
3. Capture the missing metadata from the error message:
   - Locate any `Missing*RegistrationError` (e.g. `MissingReflectionRegistrationError`, `MissingResourceRegistrationError`, or any other variant).
   - Copy the suggested JSON entry for the missing type into the corresponding section of the reachability-metadata.
4. Choose the target file and insert the entry:
   - Write to `metadata/<library-specific-metadata-directory>/reachability-metadata.json`.
   - Keep valid JSON and avoid duplicating an existing equivalent entry. If the type already exists but a method or field is missing, add only that method or field.
5. Add the missing `condition` field:
   - Infer it from the error stack trace.
   - Set the `condition` field to `{ "typeReached": "<class>" }`, where `<class>` is the first class on the stack trace whose package shares the leading namespace with the tested library's package.
   - Package overlap can be partial, full package equality is not required.
   - Example: tested library's group `org.hibernate.orm...` and the class from a stack trace `org.hibernate.resource...` is a valid match.

6. Verify and iterate:
   - Run `./gradlew test -Pcoordinates=<coordinates>` again.
   - If another missing entry appears, repeat from step 2.
   - Finish only when the test run succeeds.

## Error Patterns

Use this reference when deriving the missing entry and condition.

### Missing Registration Entry Pattern

Example error shape:

```text
Caused by: org.graalvm.nativeimage.MissingReflectionRegistrationError:
Cannot reflectively invoke constructor 'public org.hibernate.id.enhanced.SequenceStyleGenerator()'
...
add the following to the 'reflection' section of reachability-metadata.json:
{
  "type": "org.hibernate.id.enhanced.SequenceStyleGenerator",
  "methods": [{ "name": "<init>", "parameterTypes": [] }]
}
...
at org.hibernate.boot.model.internal.GeneratorBinder.instantiateGeneratorViaDefaultConstructor(...)
at org.hibernate.resource.beans.internal.Helper$2.produceBeanInstance(...)
```

### Condition Inference

For missing type `org.hibernate.id.enhanced.SequenceStyleGenerator`, a valid condition class is:

`org.hibernate.boot.model.internal.GeneratorBinder`

Reason: both share the leading namespace `org.hibernate`, which is sufficient for this workflow.

### Inactive Condition (metadata present but too late)

If GraalVM reports that metadata for an access was found but is inactive because its runtime
condition was not satisfied, treat the existing `condition` as too late for that access. Read the
access stack and move or duplicate the matching entry under the narrowest library type that is
reached *before* the access occurs. Do not reuse an unsatisfied condition merely because it relates
to the same library feature.

## Environment Troubleshooting

- If failures look unrelated or tooling looks inconsistent, verify both `JAVA_HOME` and `GRAALVM_HOME` point to a compatible GraalVM JDK distribution.
- If they are not set to GraalVM, ask the user to provide the correct GraalVM distribution path and retry.