skip to content

How do you enable and configure the metadata repository in GraalVM Native Build Tools (Gradle and Maven)?

level: middleimportance: should knowfreq 45%

answer

  1. graalvmNative { metadataRepository { enabled = true } }
  2. Maven <metadataRepository><enabled>true</enabled>
  3. version pin / uri override / module exclude
  4. Spring Boot enables by default
  5. Bundled snapshot unless overridden

basics

~10 s

In the native-build-tools plugin you turn on the metadataRepository feature. In Gradle set graalvmNative { metadataRepository { enabled = true } }; in Maven set <metadataRepository><enabled>true</enabled></metadataRepository>. Spring Boot turns it on by default.

solid answer

~40 s

The feature lives in the GraalVM Native Build Tools plugin. In Gradle you configure the `graalvmNative` extension: `metadataRepository { enabled = true }`, optionally pinning a `version` or pointing at a local `uri(...)`. In Maven you configure the `native-maven-plugin` with `<metadataRepository><enabled>true</enabled></metadataRepository>` and an optional `<version>`. When enabled, the plugin bundles or downloads a repository snapshot, matches your resolved dependencies by coordinates, and merges the metadata into the native-image config. Spring Boot's plugins enable it by default, so you rarely toggle it on manually — but you may pin a repository version for reproducibility, point at a fork/local directory for custom or newer metadata, or use per-module excludes to skip a library's metadata when it's wrong. The default source is the bundled snapshot; overriding the URI lets you use your own vetted copy.

code

kotlin · 12 lines
kotlin
// build.gradle.kts — GraalVM Native Build Tools plugin
// plugins { id("org.graalvm.buildtools.native") version "..." }

graalvmNative {
    metadataRepository {
        enabled.set(true)
        // Pin a repository release for reproducible builds (optional):
        // version.set("0.3.x")
        // Or point at a vetted local copy / fork (optional):
        // uri(file("metadata").toURI())
    }
}

go deeper

for a junior

Should know a toggle exists and that Boot enables it.

for a middle

Should recall the Gradle/Maven config blocks and the version/uri overrides.

for a senior

Should reason about pinning, forks, and per-module excludes.

for a principal

Should design a reproducible, vetted metadata strategy across teams.

**Where it lives.** The metadata repository is a *feature of the GraalVM Native Build Tools*, not a separate dependency. The Gradle plugin id is `org.graalvm.buildtools.native` (exposing the `graalvmNative` extension); the Maven equivalent is `org.graalvm.buildtools:native-maven-plugin`. **Gradle.** ```gradle graalvmNative { metadataRepository { enabled = true // turn the feature on // version = "0.3.x" // optionally pin a specific repository release // uri(file("metadata")) // optionally use a local directory / custom URI } } ``` With no `version` or `uri`, the plugin uses the metadata snapshot bundled with that plugin version. **Maven.** ```xml <plugin> <groupId>org.graalvm.buildtools</groupId> <artifactId>native-maven-plugin</artifactId> <configuration> <metadataRepository> <enabled>true</enabled> <!-- <version>0.3.x</version> --> <!-- <localPath>${project.basedir}/metadata</localPath> --> </metadataRepository> </configuration> </plugin> ``` **Spring Boot default.** Spring Boot's build integration enables `metadataRepository` by default when the native plugin is applied, which is why `./gradlew nativeCompile` or `mvn -Pnative native:compile` on a typical Boot app pulls library metadata automatically. You generally *don't* need to write the block above; you touch it only to pin, override, or disable. **Overrides & excludes.** You can: - **Pin `version`** for reproducible builds instead of relying on the bundled snapshot. - **Point `uri`/`localPath`** at a fork or internal directory to supply newer or corrected metadata before it's merged upstream. - **Exclude a module's metadata** (via the plugin's module-filtering config) when a library's published metadata is wrong for your usage and you'd rather supply your own hints. **How matching works at build time.** When enabled, the plugin reads your resolved dependency coordinates (`group:artifact:version`), looks them up in the repository's `index.json`, resolves each library's per-version metadata directory, and merges the JSON config files into the native-image arguments. No matching entry means no metadata is contributed for that jar. **Gotchas.** Enabling it does not guarantee coverage — only libraries present *and matching your exact version* contribute. Pinning an older repository version can miss metadata for newer libraries; using a newer/forked repository can add it. If metadata is subtly wrong, an exclude plus a hand-written `RuntimeHints` is the escape hatch.

  • Why might you pin the metadataRepository version instead of using the bundled default?
    Reproducibility and control: pinning decouples your build from whatever snapshot the plugin version happens to bundle, and lets you adopt a newer repository that covers a library the bundled one misses.
  • A library's published metadata is wrong for how you use it. What are your options?
    Exclude that module's metadata via the plugin's filtering config and supply your own RuntimeHints/RuntimeHintsRegistrar, or point the repository uri at a corrected fork.

saying these in an interview costs you the question

  • Thinking you must add the metadata repository as a runtime dependency
  • Believing enabling it guarantees every library is covered

context

resolving links…