Hilt Build Error on Kotlin 2.3.0: Provided Metadata instance has version 2.3.0


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