What is the GraalVM reachability-metadata repository and why does a native Spring Boot build need it?
answer
- Closed-world analysis can't see reflection/resources/proxies
- Central JSON metadata keyed by group:artifact:version
- native-build-tools metadataRepository feature
- Spring Boot enables it by default
- Covers third-party jars, not your own code
basics
~20 sIt is a community-maintained collection of GraalVM native-image config (reflection, resources, proxies) for popular third-party libraries. The build tool pulls the right config so those libraries work in a native image without you writing hints by hand.
solid answer
~40 sGraalVM's native-image compiler does closed-world static analysis: anything reached only via reflection, resources, JNI, dynamic proxies, or serialization is invisible to it and must be declared as 'reachability metadata'. Many third-party jars (drivers, JSON libs, etc.) need such metadata but don't ship it. The GraalVM reachability-metadata repository (github.com/oracle/graalvm-reachability-metadata) is a central, community-maintained store of that config, keyed by library coordinates and version. The GraalVM Native Build Tools plugin consumes it via its metadataRepository feature, so when your dependency graph includes a covered jar, the matching reflect-config/resource-config/etc. is added automatically. Spring Boot enables this by default, which is why many libraries 'just work' natively without hand-written RuntimeHints.
go deeper
Should grasp that native image can't see reflection and that the repo supplies ready-made config for libraries.
Should name the metadata categories and know Spring Boot enables it by default.
Should distinguish it from RuntimeHints and reason about version matching.
Should weigh coverage gaps, supply-chain/pinning, and contribution workflow.
## The problem GraalVM `native-image` compiles ahead-of-time under a *closed-world assumption*: it statically analyzes reachable code from `main` and includes only what it can prove is used. Dynamic behavior the analysis cannot see is invisible: - Java reflection (`Class.forName`, `Method.invoke`), - classpath resource loading, - JNI, - JDK dynamic proxies, - and serialization. If a class is instantiated only via reflection, native-image may strip it, causing runtime `ClassNotFoundException`/`NoSuchMethodException` or a missing resource. To fix this you supply **reachability metadata**: JSON files (`reflect-config.json`, `resource-config.json`, `proxy-config.json`, `serialization-config.json`, `jni-config.json`) telling the compiler to keep and register those elements. ## Why a repository Application code you own can declare hints, but you also depend on many third-party jars (JDBC drivers, Netty, Jackson, etc.) that use reflection internally. Hand-writing metadata for all of them is tedious and error-prone. The **GraalVM Reachability Metadata Repository** (`oracle/graalvm-reachability-metadata` on GitHub) is a central, open, community/vendor-maintained store of tested metadata organized per library by Maven coordinates (`group:artifact:version`). ## How it is consumed The **GraalVM Native Build Tools** (the `org.graalvm.buildtools.native` Gradle plugin / `native-maven-plugin`) has a `metadataRepository` feature. The plugin bundles a snapshot of the repository (and can fetch a specific version). During a native build it: 1. looks at your resolved dependencies, 2. finds matching metadata for their exact GAV coordinates, 3. and merges those JSON files into the native-image configuration automatically. **Spring Boot enables `metadataRepository` by default**, so covered libraries work natively with zero manual hints. ## Relationship to Spring hints This repository covers *third-party libraries*. For *your own* reflective code and for framework integration Spring uses its own `RuntimeHints` mechanism (`RuntimeHintsRegistrar`, `@ImportRuntimeHints`, `@RegisterReflectionForBinding`), emitted during AOT processing. The two are complementary: - the metadata repository handles libraries; - `RuntimeHints` handles your code and Spring's. ## When it helps / gotchas It only helps for libraries that: - (a) are in the repository and - (b) match your exact version — if a newer version has no entry, you get no metadata and may need your own hints or a fallback to an older covered version. It cannot cover truly application-specific dynamic behavior. Coverage is not universal, and metadata quality varies.
- Name two kinds of dynamic behavior that reachability metadata declares.Any two of: reflection (classes/methods/fields), classpath resources, JDK dynamic proxies, serialization, JNI access.
- Does the metadata repository replace Spring's RuntimeHints?No. The repository covers third-party libraries; RuntimeHints/RuntimeHintsRegistrar cover your own application and framework code. They work together.