Kotlin version compatibility error: binary metadata mismatch

Problem Statement

The error "Module was compiled with an incompatible version of Kotlin" occurs when there's a mismatch between the Kotlin version used to compile your project and the version used by your dependencies. This typically manifests as:

Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is 1.5.1, expected version is 1.1.16

This compatibility issue arises because Kotlin modules contain metadata that must match between the compiler and the libraries being used. When versions are incompatible, Gradle cannot properly resolve the dependencies.

Primary Solutions

Update Kotlin Version in Gradle Files

The most common solution is to ensure consistent Kotlin versions across your project configuration.

For traditional build.gradle configuration:

// In project-level build.gradle
buildscript {
    ext.kotlin_version = '1.9.23' // Use latest stable version
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.3.1"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

For declarative plugins block (modern approach):

// In settings.gradle (common in newer Flutter/Android projects)
plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.3.1" apply false
    id "org.jetbrains.kotlin.android" version "1.9.23" apply false
}

WARNING

Always verify the latest compatible versions of Android Gradle Plugin and Kotlin from official sources:

• Android Gradle Plugin Releases
• Kotlin Releases

Flutter-Specific Solution

For Flutter projects, the Kotlin version is typically configured in android/settings.gradle:

// Update this line in android/settings.gradle
id "org.jetbrains.kotlin.android" version "1.9.23" apply false

After making changes, perform a clean rebuild:

flutter clean
flutter pub get

React Native Solution

React Native projects may need to restrict dependency resolution to prevent pulling incompatible versions:

// In android/build.gradle
allprojects {
    repositories {
        exclusiveContent {
            filter {
                includeGroup "com.facebook.react"
            }
            forRepository {
                maven {
                    url "$rootDir/../node_modules/react-native/android"
                }
            }
        }
        // Other repositories...
    }
}

Alternative Approaches

Clear Gradle Cache

Sometimes the issue persists due to cached artifacts:

1. Delete the cache directory: [Project]/.gradle/caches
2. In Android Studio: File > Invalidate Caches / Restart
3. Rebuild the project

Check Dependency Compatibility

If updating Kotlin isn't feasible, identify and downgrade incompatible dependencies:

./gradlew app:dependencies

Examine the output for libraries requiring specific Kotlin versions and consider downgrading those dependencies instead.

Library Developer Considerations

If you're developing a library for consumption by other projects:

compileKotlin {
    kotlinOptions {
        jvmTarget = '1.8'
        languageVersion = '1.4' // Target older version for compatibility
        apiVersion = '1.4'
    }
}

INFO

Setting languageVersion and apiVersion to older Kotlin versions ensures your library remains compatible with projects using older Kotlin compilers, at the cost of not being able to use newer language features.

Common Pitfalls

1. Multiple version declarations: Ensure you're updating the Kotlin version in all relevant files (both build.gradle and settings.gradle in some cases)

2. Plugin compatibility: Android Gradle Plugin versions have specific Kotlin version requirements. Check compatibility matrices before updating.

3. Cached artifacts: Always perform a clean build after changing versions: ./gradlew clean or flutter clean

4. Transitive dependencies: Some dependencies may bring in their own Kotlin stdlib versions. Use dependency constraints if needed:

// In app-level build.gradle
dependencies {
    constraints {
        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
            version { strictly '1.9.23' }
        }
        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
            version { strictly '1.9.23' }
        }
    }
}

Prevention

To avoid future compatibility issues:

1. Keep your Kotlin and Android Gradle Plugin versions updated regularly
2. Use version variables to ensure consistency across build files
3. Check release notes for breaking changes when updating
4. Consider using version catalogs for centralized dependency management

By maintaining version consistency across your project and its dependencies, you can prevent Kotlin metadata compatibility issues and ensure smooth builds.