fix(expo): add Kotlin metadata version compatibility flag for clerk-android by chriscanin · Pull Request #8152 · clerk/javascript

chriscanin · 2026-03-23T14:39:05Z

Summary

Fixes Kotlin metadata version mismatch errors during Android builds with Expo SDK 54/55.

The clerk-android native dependency is compiled with Kotlin 2.3.x, but Expo SDK 54 uses Kotlin 2.1.20 and SDK 55 uses Kotlin 2.1.x. When Gradle resolves kotlinx-serialization-core:1.10.0 (a transitive dependency from clerk-android), the older Kotlin compiler can't read the 2.3.x metadata, causing :app:compileDebugKotlin to fail with:

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

The fix adds -Xskip-metadata-version-check to all project modules via rootProject.allprojects in the @clerk/expo build.gradle. This allows the older compiler to read newer metadata without failing.

Wrapped in try/catch for forward compatibility with Gradle's Isolated Projects feature, which may block cross-project configuration in future versions.

Reported by

Tom (internal, via Plain thread)
Community user (https://github.com/erichli1/0319-expo-android-bug)

Test plan

Android build with Expo SDK 54 succeeds (no Kotlin metadata error)
Android build with Expo SDK 55 succeeds (no Kotlin metadata error)
Verify using the community repro: https://github.com/erichli1/0319-expo-android-bug

🤖 Generated with Claude Code

Summary by CodeRabbit

Bug Fixes
- Prevents Kotlin metadata version mismatches that could cause Android build failures (e.g., “incompatible version of Kotlin” during :app:compileDebugKotlin), improving build reliability for projects using Expo SDK 54/55 and similar setups.
Chores
- Added a changeset to publish a patch release addressing the issue.

…ndroid clerk-android is compiled with Kotlin 2.3.x but Expo SDK 54/55 ships Kotlin 2.1.x. This causes 'incompatible version of Kotlin' metadata errors during Android builds. Adding -Xskip-metadata-version-check to all project modules allows the older compiler to read the newer metadata without failing.

vercel · 2026-03-23T14:39:10Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 23, 2026 9:44pm

changeset-bot · 2026-03-23T14:39:15Z

🦋 Changeset detected

Latest commit: 0cc7975

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/expo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-03-23T14:41:20Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8152

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8152

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8152

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8152

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8152

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8152

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8152

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8152

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8152

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8152

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8152

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8152

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8152

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8152

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8152

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8152

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8152

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8152

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8152

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8152

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8152

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8152

commit: 0cc7975

coderabbitai · 2026-03-23T14:42:05Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: f0338965-a2cd-44f9-ae58-b5d0f589691e

📥 Commits

Reviewing files that changed from the base of the PR and between b480d14 and 0cc7975.

📒 Files selected for processing (1)

packages/expo/android/build.gradle

📝 Walkthrough

Walkthrough

The Android Gradle build was changed to ensure the Kotlin compiler flag -Xskip-metadata-version-check is applied consistently. The module’s kotlinOptions still includes the flag, and a cross-project configuration iterates rootProject.allprojects and uses configureEach to add the flag to all KotlinCompile tasks’ compilerOptions.freeCompilerArgs. The cross-project block is wrapped in a try/catch. File comments were expanded to describe the Kotlin metadata/version mismatch between clerk-android (Kotlin 2.3.x) and typical Expo/RN Kotlin (e.g., 2.1.x).

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a Kotlin metadata version compatibility flag to fix clerk-android build issues in Expo.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/expo/android/build.gradle`:
- Around line 78-94: Add automated Android build tests that verify the Kotlin
metadata skip flag is applied and prevents the incompatible-Kotlin metadata
error for Expo SDK 54 and 55; create CI jobs (or unit/functional tests) that
build an example Expo app using SDK 54 and SDK 55 with the current change to
packages/expo/android/build.gradle (the block that configures
rootProject.allprojects ->
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile) ->
compilerOptions.freeCompilerArgs.add('-Xskip-metadata-version-check')) and
include the linked repro project as a test case to reproduce the original
failure, asserting that :app:compileDebugKotlin succeeds; ensure these tests run
in the repo CI matrix so regressions are caught before merge.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: b8314964-9c24-486a-af9d-1aa6d7cfa2e4

📥 Commits

Reviewing files that changed from the base of the PR and between 3efdd2c and b8a6840.

📒 Files selected for processing (1)

packages/expo/android/build.gradle

coderabbitai · 2026-03-23T14:42:08Z

packages/expo/android/build.gradle

+// clerk-android is compiled with Kotlin 2.3.x, but Expo/RN projects typically use an older
+// Kotlin version (e.g. 2.1.x). This causes "incompatible version of Kotlin" metadata errors
+// at :app:compileDebugKotlin. Applying -Xskip-metadata-version-check allows the older
+// compiler to read 2.3.x metadata without failing.
+try {
+  rootProject.allprojects {
+    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
+      compilerOptions {
+        freeCompilerArgs.add('-Xskip-metadata-version-check')
+      }
+    }
+  }
+} catch (Exception ignored) {
+  // Future Gradle versions with Isolated Projects may block cross-project configuration.
+  // In that case, users should add '@clerk/expo' to their app.json plugins array instead,
+  // which applies the flag via the config plugin's withClerkAndroid.
+}


⚠️ Potential issue | 🟠 Major

Add merge-gating Android build tests for Expo SDK 54/55.

This change modifies Kotlin compilation behavior across all projects, but no tests were added. Please add automated Android build coverage (SDK 54 + SDK 55, ideally including the linked repro) before merge to prevent regressions in the exact failure path this PR targets.

As per coding guidelines, "If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@packages/expo/android/build.gradle` around lines 78 - 94, Add automated Android build tests that verify the Kotlin metadata skip flag is applied and prevents the incompatible-Kotlin metadata error for Expo SDK 54 and 55; create CI jobs (or unit/functional tests) that build an example Expo app using SDK 54 and SDK 55 with the current change to packages/expo/android/build.gradle (the block that configures rootProject.allprojects -> tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile) -> compilerOptions.freeCompilerArgs.add('-Xskip-metadata-version-check')) and include the linked repro project as a test case to reproduce the original failure, asserting that :app:compileDebugKotlin succeeds; ensure these tests run in the repo CI matrix so regressions are caught before merge.

This is a good idea @coderabbitai but these fixes have been manually validated. I would like to get some testing and merge gating in as soon as possible.

@chriscanin, understood — glad the manual validation confirmed the fix works. Would you like me to open a follow-up GitHub issue to track adding automated Android build tests / CI merge gating for Expo SDK 54 and 55 (including the linked community repro)? That way the work doesn't get lost and can be prioritized separately from this merge.

tmilewski

👍 Just need a changeset here.

chriscanin · 2026-03-23T15:42:38Z

Adding changeset now.

brkalow · 2026-03-23T17:12:29Z

packages/expo/android/build.gradle

+// clerk-android is compiled with Kotlin 2.3.x, but Expo/RN projects typically use an older
+// Kotlin version (e.g. 2.1.x). This causes "incompatible version of Kotlin" metadata errors
+// at :app:compileDebugKotlin. Applying -Xskip-metadata-version-check allows the older
+// compiler to read 2.3.x metadata without failing.


are there compatibility concerns beyond the version check here that we need to consider?

I have addressed these with Sam earlier last week, but the issue is that clerk-android's transitive dependencies (specifically kotlinx-serialization-core:1.10.0) are compiled with Kotlin 2.3.x, while Expo SDK 54 & 55 ships Kotlin 2.1.x so the -Xskip-metadata-version-check flag only bypasses the conservative version check on metadata reading. It does not skip the binary compatibility validation.

I believe Kotlin maintains backward compatibility for metadata across minor versions (2.1 reading 2.3). Ideally clerk-android and its peer dependencies will be compiled with the version that expo ships, but it looks like expo is behind by 2 minor versions, and although Sam and I knocked kotlin down to be compiled with 2.1 as well, some of the peer dependencies are still on 2.3, which is causing the error to pop up.

When Sam returns from vacation, I will make sure to meet with him and discuss this, to ensure that the expo and android SDK's are synced up in the best way possible (and with testing too!)

This is a summary from claude that may help to clear things up as well:

The core issue: clerk-android currently compiles against Kotlin 2.3.x, while Expo SDK 54/55 ships Kotlin 2.1.x. This creates a metadata version mismatch for transitive dependencies — most notably kotlinx-serialization-core:1.10.0, which is compiled with Kotlin 2.3.0 metadata that a 2.1.x compiler refuses to read by default.

Why this flag is safe: -Xskip-metadata-version-check only bypasses the conservative metadata version check — it does not skip binary compatibility validation. Kotlin maintains backward compatibility for metadata across minor versions, so a 2.1.x compiler reading 2.3.x metadata works correctly in practice. The strict check is just being overly cautious.

Why the Android SDK's transitive deps are on 2.3.x: The Android SDK doesn't currently pin or constrain its transitive dependency versions. kotlinx-serialization-json is declared as an api() dependency, which means kotlinx-serialization-core flows through to all consumers. Since kotlinx-serialization:1.10.0 requires Kotlin 2.3.0 (per the kotlinx.serialization compatibility matrix), any consumer on Kotlin 2.1.x will hit this metadata error. Similarly, ktor:3.4.0 brings in its own set of 2.3.x-compiled transitive deps.

What we're doing about it: This flag is the right short-term fix to unblock users. Longer term, I'm working with Sam to ensure the Android SDK and its dependency tree are properly aligned with the Kotlin version that Expo ships, whether that means pinning transitive dependency versions, adding dependency constraints, or maintaining a compatible build configuration specifically for Expo consumers. We'll also be adding proper integration testing to catch these mismatches before they reach users.

👍 let's add a TODO here so we have a flag to come back and adjust this

TODO comment has been added. I am also making a linear ticket for this, will link here when completed.

github-actions bot added the expo label Mar 23, 2026

vercel bot deployed to Preview March 23, 2026 14:39 View deployment

coderabbitai bot reviewed Mar 23, 2026

View reviewed changes

chriscanin self-assigned this Mar 23, 2026

chriscanin requested review from brkalow, swolfand and tmilewski and removed request for swolfand March 23, 2026 15:30

tmilewski approved these changes Mar 23, 2026

View reviewed changes

chore: add changeset for Kotlin metadata version fix

b480d14

vercel bot deployed to Preview March 23, 2026 15:44 View deployment

brkalow reviewed Mar 23, 2026

View reviewed changes

chore: add TODO comment for kotlin metadata version check flag

0cc7975

vercel bot deployed to Preview March 23, 2026 21:44 View deployment

Conversation

chriscanin commented Mar 23, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Reported by

Test plan

Summary by CodeRabbit

Uh oh!

vercel bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chriscanin Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

tmilewski left a comment

Choose a reason for hiding this comment

Uh oh!

chriscanin commented Mar 23, 2026

Uh oh!

brkalow Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

chriscanin Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

chriscanin Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

brkalow Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

chriscanin Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chriscanin commented Mar 23, 2026 •

edited by coderabbitai bot

Loading

vercel bot commented Mar 23, 2026 •

edited

Loading

changeset-bot bot commented Mar 23, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 23, 2026 •

edited

Loading

coderabbitai bot commented Mar 23, 2026 •

edited

Loading

coderabbitai bot Mar 23, 2026 •

edited

Loading