Kotlin "incompatible metadata version" in CI

A dependency was compiled with a newer Kotlin version than the compiler in your build. The class metadata format is ahead of what your compiler can read.

What this error means

Compilation fails with a message that a class was compiled with an incompatible/newer version of Kotlin and the compiler version should be updated. It is deterministic given the versions.

gradle

e: ... Class 'com.example.Widget' was compiled with an incompatible
version of Kotlin. The binary version of its metadata is 2.1.0,
expected version is 1.9.0.

Common causes

Dependency built with a newer Kotlin

A library was published with Kotlin 2.x metadata while your project still uses an older compiler that cannot read it.

Mismatched Kotlin Gradle plugin and stdlib

The Kotlin Gradle plugin version and an explicitly pinned stdlib diverge, producing inconsistent metadata.

How to fix it

Upgrade the Kotlin compiler

Bump the Kotlin Gradle plugin to a version that can read the dependency metadata.

build.gradle.kts

plugins {
  kotlin("jvm") version "2.1.0"
}

Align plugin and stdlib versions

Let the Kotlin plugin manage the stdlib version instead of pinning it.
Remove explicit kotlin-stdlib version overrides.
Verify all Kotlin modules share one plugin version.

Downgrade the dependency if you cannot upgrade Kotlin

Pin the library to a release built with a Kotlin version your compiler supports.

How to prevent it

Keep the Kotlin plugin current with your dependencies.
Use a version catalog to align Kotlin artifacts.
Read release notes before bumping libraries.