Debugging log · Gradle

"Incompatible version of Kotlin" — the day Firebase broke my build

I added Firebase to a game I was building, bumped the Firebase BoM to the latest while I was at it, hit Sync — and the whole project stopped compiling. The error wasn't about Firebase at all. It was a wall of red about Kotlin metadata versions. If you've just updated a dependency and suddenly nothing builds, this is probably what bit you too.

The short version: a library you pulled in was compiled with a newer Kotlin than your project's Kotlin plugin understands. The fix is to line the versions up — usually by raising your Kotlin (and Compose compiler) version, or by pinning the dependency to one built for the Kotlin you're on.

The error

It looks roughly like this, repeated for a bunch of classes:

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

Two numbers matter here. "binary version … is X" is the Kotlin the dependency was built with. "expected version is Y" is what your Kotlin toolchain can read. When X is newer than Y, your compiler is being handed bytecode it doesn't fully understand, so it refuses.

Why the Firebase BoM set it off

The Firebase BoM (Bill of Materials) is a single version that pins all the Firebase libraries together. When I bumped the BoM, it quietly pulled in newer Firebase artifacts — and some of those, along with their transitive Kotlin/AndroidX dependencies, were compiled with a newer Kotlin than my project's Kotlin Gradle plugin. Nothing in my own code changed; the metadata mismatch came in through the dependency graph. That's what makes this confusing: the thing you changed (the BoM) isn't the thing named in the error (Kotlin).

How I fixed it

The goal is simple: make your Kotlin at least as new as whatever the noisiest dependency was built with.

1. Read the numbers, don't guess

Note the highest "binary version" in the errors. That tells you the minimum Kotlin you need to be on. If it says the metadata is 2.1.x, your Kotlin plugin needs to be a 2.1-capable version or newer.

2. Bump the Kotlin Gradle plugin

Raise the Kotlin plugin version so it can read that metadata. In a modern setup that's in your version catalog or the top-level Gradle file:

// libs.versions.toml (or your build.gradle plugins block)
kotlin = "2.x.x"   // at least as new as the dependency's metadata

3. Keep the Compose compiler in step

If you use Compose, its compiler is tied to your Kotlin version. On older setups a raw kotlinCompilerExtensionVersion mismatch throws a similar wall of errors; on newer ones the Compose compiler ships with the Kotlin plugin, so bumping Kotlin fixes both at once. Either way, don't leave the Compose compiler pinned to an old Kotlin.

4. If you can't move Kotlin, pin the dependency down instead

Sometimes you're stuck on a Kotlin version for other reasons. Then go the other way: pin the Firebase BoM (or the offending library) back to a release that was built for the Kotlin you're on. You lose the newest features but the build goes green. Check the library's release notes for which Kotlin each version targets.

Rule of thumb: your Kotlin ≥ the dependency's metadata version. Raise Kotlin to meet the library, or lower the library to meet your Kotlin — never leave them crossed.

How to confirm it's really fixed

Do a clean build, not just a Gradle sync — stale outputs can hide or fake the error.
Run ./gradlew app:dependencies if you want to see exactly which versions the BoM resolved to, so the next bump isn't a surprise.
Change one version at a time. Bumping Kotlin, the BoM, and AGP together makes it impossible to tell which one moved the needle.

Version numbers here are illustrative; use the exact ones from your own error output and the library's release notes.