Hilt Unsupported Metadata Version in Kotlin

Problem

When using Dagger Hilt with Kotlin, you may encounter the error:

error: [Hilt]
Unsupported metadata version. Check that your Kotlin version is >= 1.0: java.lang.IllegalStateException: Unsupported metadata version. Check that your Kotlin version is >= 1.0
at dagger.internal.codegen.kotlin.KotlinMetadata.metadataOf(KotlinMetadata.java:206)

This error occurs due to version incompatibility between your Kotlin version and Hilt dependencies. The metadata format used by Kotlin changes between versions, and Hilt needs to be compatible with your specific Kotlin version to process annotations correctly.

Root Cause

The core issue is mismatched versions between:

• Kotlin compiler version
• Hilt plugin version
• Hilt dependency versions
• Kotlin metadata processor versions

Hilt uses Kotlin metadata to generate code during compilation, and when these versions are incompatible, the metadata cannot be properly parsed.

Solutions

1. Version Compatibility Matching

The most reliable solution is to ensure all your Hilt and Kotlin versions are compatible. Here are the recommended version pairings:

Kotlin 2.0.0

// Project-level build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.android") version "2.0.0" apply false
    id("com.google.dagger.hilt.android") version "2.51.1" apply false
}

// App-level build.gradle.kts
implementation("com.google.dagger:hilt-android:2.51.1")
kapt("com.google.dagger:hilt-android-compiler:2.51.1")

Kotlin 1.9.0+

// Project-level build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
    id("com.google.dagger.hilt.android") version "2.48" apply false
}

// App-level build.gradle.kts
implementation("com.google.dagger:hilt-android:2.48")
kapt("com.google.dagger:hilt-android-compiler:2.48")

Kotlin 1.8.0

// Project-level build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.android") version "1.8.0" apply false
    id("com.google.dagger.hilt.android") version "2.44" apply false
}

// App-level build.gradle.kts
implementation("com.google.dagger:hilt-android:2.44")
kapt("com.google.dagger:hilt-android-compiler:2.44")

Groovy DSL

// For Groovy users with Kotlin 1.9.0
plugins {
    id 'org.jetbrains.kotlin.android' version '1.9.0' apply false
    id 'com.google.dagger.hilt.android' version '2.48' apply false
}

// App-level build.gradle
implementation 'com.google.dagger:hilt-android:2.48'
kapt 'com.google.dagger:hilt-compiler:2.48'

2. Using Version Variables

To avoid inconsistent versions, define a version variable:

Kotlin DSL

// Project-level build.gradle.kts
val hiltVersion = "2.51.1"

plugins {
    id("com.google.dagger.hilt.android") version hiltVersion apply false
}

// App-level build.gradle.kts
implementation("com.google.dagger:hilt-android:$hiltVersion")
kapt("com.google.dagger:hilt-android-compiler:$hiltVersion")

Groovy DSL

// Project-level build.gradle
ext {
    hilt_version = '2.51.1'
}

plugins {
    id 'com.google.dagger.hilt.android' version "$hilt_version" apply false
}

// App-level build.gradle
implementation "com.google.dagger:hilt-android:$hilt_version"
kapt "com.google.dagger:hilt-compiler:$hilt_version"

3. Using Gradle Version Catalogs

For better dependency management, use version catalogs in libs.versions.toml:

libs.versions.toml

[versions]
kotlin = "2.0.0"
hilt = "2.51.1"
ksp = "2.0.0-1.0.23"

[libraries]
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }
androidx-hilt-navigation = { group = "androidx.hilt", name = "hilt-navigation-compose", version = "1.2.0" }

[plugins]
dagger-hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

Project-level build.gradle.kts

plugins {
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.dagger.hilt) apply false
    alias(libs.plugins.ksp) apply false
}

App-level build.gradle.kts

plugins {
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.dagger.hilt)
    alias(libs.plugins.ksp)
}

dependencies {
    implementation(libs.hilt.android)
    kapt(libs.hilt.compiler)
    implementation(libs.androidx.hilt.navigation)
}

4. Additional Configuration

Add this kapt configuration to handle error types correctly:

kapt {
    correctErrorTypes = true
}

Common Mistakes to Avoid

WARNING

Version Mismatch: Using different versions for Hilt plugin and dependencies is a common mistake. Always keep them synchronized.

DANGER

Outdated Documentation: The Hilt documentation changes frequently. Always check the official Hilt setup guide for the latest compatible versions.

INFO

Kotlin Version Compatibility: New Kotlin versions often require updated Hilt versions. Check compatibility before upgrading.

Troubleshooting

If you still encounter issues:

1. Check the official compatibility matrix on the Dagger Hilt GitHub page
2. Use the stacktrace for detailed error information:

   ./gradlew build --stacktrace

3. Clean and rebuild your project:

   ./gradlew clean build

4. Invalidate caches and restart Android Studio

Version Compatibility Reference

Kotlin Version	Hilt Version	Notes
2.0.0+	2.51.1+	Latest stable
1.9.0+	2.48+	Widely compatible
1.8.0	2.44	Legacy support
1.7.0	2.42	Older versions

TIP

Always check for the latest versions on the official Hilt documentation as compatibility changes with new releases.

Conclusion

The "Unsupported metadata version" error in Hilt is strictly a version compatibility issue. By ensuring your Kotlin version, Hilt plugin version, and Hilt dependency versions are all compatible, you can resolve this error and maintain a stable development environment.

Keep your dependencies updated and use version variables or version catalogs to maintain consistency across your project configuration.