error: [Hilt] Provided Metadata instance has version 2.3.0, while maximum supported version is 2.2.0.
This article explains the background of this error and introduces a new solution available since Dagger 2.57.
🤔 🧑🏻💻 1. Cause of the Error
This error occurs because kotlin-metadata-jvm, a library used internally by Dagger/Hilt, cannot understand the newer Kotlin metadata format (version 2.3.0).
Shading (Inshading) explained:
- Shading means that a dependency is relocated and bundled inside another library’s JAR.
- In earlier Dagger versions, kotlin-metadata-jvm was shaded (hidden) inside Dagger itself.
- As a result, developers could not override or update it, even if Kotlin introduced a new metadata version.
- This tightly coupled Dagger’s compatibility to a specific Kotlin version and forced users to wait for a Dagger release.
🤔 🧑🏻💻 2. What Changed in Dagger 2.57
Starting from Dagger 2.57, kotlin-metadata-jvm is unshaded (no longer hidden).
This means:
- The dependency is now resolved normally via Gradle
- Developers can explicitly specify a newer version without waiting for a Dagger update
This architectural change significantly improves Kotlin version agility.
🤔 🧑🏻💻 3. Solution: Explicitly Declare the Dependency
If you are using Kapt
Kapt runs through the Java compiler and is more sensitive to metadata incompatibility.
dependencies {
// Add the latest metadata library to kapt
kapt("org.jetbrains.kotlin:kotlin-metadata-jvm:2.3.0-Beta1")
}
If you are using KSP
KSP is directly integrated with the Kotlin compiler, so this error is less likely.
If needed, you can still specify it explicitly.
dependencies {
// Add to ksp configuration
ksp("org.jetbrains.kotlin:kotlin-metadata-jvm:2.3.0-Beta1")
}
Recommended: Force the version globally
If multiple modules are affected, this is the most reliable approach.
configurations.all {
resolutionStrategy {
force "org.jetbrains.kotlin:kotlin-metadata-jvm:2.3.0-Beta1"
}
}
🤔 🧑🏻💻 4. Summary
- If you are using Dagger 2.57 or later, you do not need to wait for a new Dagger release.
- When the error appears, explicitly add the latest kotlin-metadata-jvm to your kapt or ksp configuration.
- In general, migrating to KSP is recommended due to better compatibility and performance.
- Developers who want to adopt the latest Kotlin features early should definitely apply this setup.
👉 Upgrade kotlin-metadata-jvm to support Kotlin 2.3.0 · Issue #5001 · google/dagger
