kmp-build-failure-triage
Skill15 starsChanged 25 days agoApache-2.0View on GitHub
Use when a Kotlin Multiplatform build fails on Android or iOS — Gradle, KSP, Kotlin/Native link or Xcode errors such as "Undefined symbols for architecture arm64", "framework not found", "No such module", "Could not resolve" in commonMain, expect/actual mismatches, "Command PhaseScriptExecution failed", JAVA_HOME or sandbox errors in the Xcode run script, Kotlin daemon OutOfMemoryError, configuration cache problems, "Duplicate class", or R8 missing classes.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- android-to-kmp-migrationSkill
- compose-design-system-componentSkill
- compose-multiplatform-localizationSkill
- compose-multiplatform-navigationSkill
- compose-multiplatform-screenSkill
- figma-to-mobile-uiSkill
- kmp-api-endpointSkill
- kmp-build-checkSkill
- kmp-ci-github-actionsSkill
- kmp-code-reviewSkill
- kmp-crash-triageSkill
- kmp-data-layerSkill
- kmp-dev-machine-cleanupSkill
- kmp-expect-actualSkill
- kmp-feature-moduleSkill
- kmp-flaky-test-triageSkill
- kmp-gradle-version-catalogSkill
- kmp-koin-diSkill
- kmp-module-healthSkill
- kmp-room-databaseSkill
- kmp-secure-storageSkill
- kmp-swiftui-interopSkill
- kmp-test-coverage-backfillSkill
- kmp-testing-patternsSkill
- kmp-xcframework-distributionSkill
- mobile-accessibility-test-idsSkill
- mobile-bug-fixSkill
- mobile-feature-implementSkill
- mobile-feature-planSkill
- mobile-performance-fixSkill
- mobile-platform-paritySkill
- mobile-releaseSkill
- mobile-security-reviewSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 110
Look the symptom up in the quick reference below.
- Very specific: line 116
Do not open with ./gradlew clean, deleting ~/.gradle, ~/.konan or DerivedData.
- Very specific: line 124
Run the matrix in Verify. Done when every check is PASS, or NOT RUN with a reason.
- Very specific: line 169
No macOS, no Xcode, or no simulator runtime (xcrun simctl list runtimes) → the iOS checks are NOT RUN — <reason>.
- Very specific: line 171
If the original failure was release-only (R8, release link), also run the release variant (assembleRelease, linkReleaseFrameworkIosArm64).
- Very specific: line 173
If the fix touched linker options, check the symbol the runtime needs is present (for SQLite: nm -gU <framework binary> | grep …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
KMP build failure triage
The last line of a failed build is almost never the cause. Find the first real error, name the layer it belongs to, make the smallest fix, then prove that both platforms still build. A KMP change that fixes iOS can break Android, and the reverse.
When to use
- Any red build in a KMP project: Gradle sync/configuration, dependency resolution, Kotlin compile (common or platform), KSP, Kotlin/Native framework link, Swift compile, Xcode link, Android dex/R8.
- "Works on Android, fails on iOS" (or the reverse), "works locally, fails on CI", "broke after a version bump".
- Link-time configuration that only shows up at runtime on iOS (for example a database driver that crashes on first use).
When not to use
- The app builds and then crashes for a reason unrelated to build configuration — use
kmp-crash-triage. - Nothing is failing yet and you only want to confirm a change builds on both platforms — use
kmp-build-check. - Builds succeed but are slow — see the Kotlin/Native build performance skill.
- Packaging, SPM and versioning problems after the framework exists — use
kmp-xcframework-distribution. Swift API shape questions — usekmp-swiftui-interop.
Step 0 — Read the project first
Collect the facts before touching anything. Most "mystery" failures are a version or environment mismatch that these commands expose.
./gradlew --version # Gradle and the JVM Gradle actually runs on
java -version 2>&1 | head -1; /usr/libexec/java_home -V 2>&1 | head -5
xcodebuild -version; uname -m # Xcode, and arm64 vs x86_64 host
grep -nE '^(kotlin|agp|android|compose|ksp|skie|kmmbridge|room|sqlite|ktor|coroutines|serialization)' \
gradle/libs.versions.toml
grep distributionUrl gradle/wrapper/gradle-wrapper.properties
cat gradle.properties # jvmargs, configuration cache, kotlin.native.* flags
grep -rnE "iosArm64|iosSimulatorArm64|iosX64|androidTarget|androidLibrary|jvm\(" --include=*.gradle.kts . | head
git log --oneline -5 && git diff --stat HEAD~1 # what changed right before it brokeAlso establish: does it fail locally, on CI, or both; on a clean checkout; on one machine architecture only. Follow the project's existing build conventions (version catalog, convention plugins, CI scripts) — fix inside them, never around them.
Workflow
1. Reproduce on the command line with a full log
./gradlew <failing-task> --stacktrace --console=plain 2>&1 | tee build.log
xcodebuild -project iosApp/iosApp.xcodeproj -scheme iosApp \
-destination 'generic/platform=iOS Simulator' build 2>&1 | tee xcode.logIDE summaries hide the first error. Add --info only when the plain log does not explain the
failure. Done when a log file contains the failure.
2. Find the first real error
grep -nE '^e: |error:|What went wrong|Caused by:|Undefined symbols|ld: |FAILED|Exception' build.log | head -40- Kotlin compiler errors start with
e:(warningsw:). The firste:is the cause; later ones usually cascade from it. - Gradle's
* What went wrong:names the failed task; the reason is above it or in the deepestCaused by:of the stack trace. - Linker failures: read the
Undefined symbols for architecture …block — the symbol name and itsreferenced fromline.ld: symbol(s) not foundandclang: error: linker command failedare just the footer. - Xcode:
Command PhaseScriptExecution failed with a nonzero exit codeonly says the run script failed. Expand that step in the build log (Report navigator) and read the Gradle output inside it. - CI: use the raw job log, not the annotated summary; find the first failing step.
Done when you can quote one line that states the cause.
3. Classify the layer
| Layer | Recognise it by | Smallest task that reproduces it |
| Environment | JDK, Xcode, memory, sandbox, PATH messages | ./gradlew help |
| Dependency resolution | Could not resolve, No matching variant, metadata/ABI version errors | ./gradlew :shared:dependencies (filter for the failing configuration) |
| Gradle configuration | Fails before any task runs; plugin, DSL or configuration-cache errors | ./gradlew help |
| Kotlin compile (common) | e: in commonMain files | ./gradlew :shared:compileCommonMainKotlinMetadata |
| Kotlin compile (platform) | e: only for one target; expect/actual errors | :shared:compileKotlinIosSimulatorArm64 / the Android compile task |
| KSP / code generation | Missing generated class; works on one target only | :shared:kspKotlinIosSimulatorArm64 (list: tasks --all | grep -i ksp) |
| Kotlin/Native link | linkDebugFramework… or linkDebugTest… fails; Undefined symbols | :shared:linkDebugFrameworkIosSimulatorArm64 |
| Swift compile | No such module, cannot find … in scope, has no member | xcodebuild … build |
| Xcode link | framework not found, Undefined symbols in the app target | xcodebuild … build |
| Android packaging | Duplicate class, D8/R8 errors, missing keep rules | :composeApp:assembleRelease (or the failing variant) |
Task names differ with plugin setup; confirm with ./gradlew :shared:tasks --all | grep -iE "compile|link|ksp".
4. Apply the smallest fix
Look the symptom up in the quick reference below; the full symptom → cause → fix catalog, grouped by layer, is in references/error-catalog.md. Change one thing, re-run the smallest task, repeat.
5. Caches last, and only the one you suspect
Do not open with ./gradlew clean, deleting ~/.gradle, ~/.konan or DerivedData. Clear a cache
only when the evidence points to it (the error names a file that no longer exists, a clean checkout
builds, the failure follows one machine). Clear the specific cache, and ask the user before
deleting any directory. Stop Gradle daemons with ./gradlew --stop first — a daemon started with
different settings (sandboxed, different JDK) is a cache too.
6. Rebuild both platforms
Run the matrix in Verify. Done when every check is PASS, or NOT RUN with a reason.
7. Report
One line of root cause, the fix, what was verified (with PASS / FAIL / NOT RUN), and any workaround that must be removed later (a disabled cache, a pinned version, a suppressed check).
Quick reference
| Symptom | First thing to check |
Undefined symbols for architecture arm64: with _sqlite3_… | Static framework needs system SQLite linked by the consumer — or you use a bundled SQLite and should not link the system one |
Undefined symbols only in linkDebugTest… | Linker options set on binaries.framework but not binaries.all |
| Swift sees a type prefixed with a module name, or not at all | Module is api(...) but not export(...) in the framework block (or the reverse) |
No such module 'SharedKit' | Framework not built for this configuration/architecture; run script after Compile Sources; product not linked |
framework not found / ld: framework 'SharedKit' not found | Search paths or OTHER_LDFLAGS point at a framework that was never built for this SDK/config |
Could not find module … for target 'x86_64-apple-ios-simulator' | No iosX64 slice and the host/simulator is x86_64 |
Could not resolve in commonMain / No matching variant | Library has no KMP (iOS) variant — move it to androidMain or pick a KMP library |
… compiled with an incompatible version of Kotlin | A dependency was built with a newer Kotlin |
| expect/actual "has no actual" / "no corresponding expected" | Missing actual for one target, or package/signature mismatch |
| Room works on Android, iOS crashes on first DB use | KSP compiler not added for every iOS target |
Starting in Kotlin 2.0, the Compose Compiler Gradle plugin is required | Apply org.jetbrains.kotlin.plugin.compose at the Kotlin version |
| iOS build broke right after a Kotlin bump; Android fine | SKIE / KSP / Compose Multiplatform do not support that Kotlin version yet |
Run script: JAVA_HOME is not set / wrong Java version | Xcode does not load your shell profile |
Run script: Sandbox: … deny(1) file-read-data | User Script Sandboxing is on |
OutOfMemoryError / daemon disappeared during iOS link | org.gradle.jvmargs too small — the Kotlin/Native compiler runs in the Gradle daemon |
Configuration cache problems found in this build | A task or plugin touches Project at execution time |
Duplicate class … found in modules … | Same classes from two artifacts |
Missing classes detected while running R8 | Missing keep/-dontwarn rules; check missing_rules.txt |
Verify
Report every check as PASS, FAIL or NOT RUN with the reason. Never mark a check that did not
run as passed. Adjust task names to the project (Step 0).
./gradlew :shared:compileCommonMainKotlinMetadata # common code
./gradlew :composeApp:assembleDebug # Android app (or the project's app module)
./gradlew :shared:testDebugUnitTest # JVM/Android unit tests (name varies by plugin)
./gradlew :shared:linkDebugFrameworkIosSimulatorArm64 # iOS framework link
./gradlew :shared:iosSimulatorArm64Test # iOS tests (links the test executable too)
xcodebuild -project iosApp/iosApp.xcodeproj -scheme iosApp \
-destination 'generic/platform=iOS Simulator' build # the iOS app itself- No macOS, no Xcode, or no simulator runtime (
xcrun simctl list runtimes) → the iOS checks areNOT RUN — <reason>. Say that CI must cover them. - If the original failure was release-only (R8, release link), also run the release variant
(
assembleRelease,linkReleaseFrameworkIosArm64). - If the fix touched linker options, check the symbol the runtime needs is present (for SQLite:
nm -gU <framework binary> | grep _sqlite3_sourceidwhen a bundled copy is expected).
Common mistakes
| Mistake | Why it bites | Fix |
| Fixing the last error in the log | It is a cascade or a footer | Fix the first e: / first Undefined symbols entry |
clean + deleting caches as step one | Slow, hides the real cause, often "fixes" nothing | Classify first; clear one cache with evidence, after asking |
| Verifying only the platform that failed | KMP fixes cross platforms (api/export, source sets, linker flags) | Run the full matrix |
Adding -lsqlite3 to silence undefined SQLite symbols | With a bundled SQLite driver it can make the bundled copy disappear from the binary | Decide system vs bundled; link exactly one |
transitiveExport = true to make a type visible | Exports everything; longer links, bigger binary | api + export the one module |
| Bumping Kotlin alone | SKIE, KSP, Compose Multiplatform and AGP have compatibility ranges | Bump the set together; check each project's compatibility notes |
Setting org.gradle.java.home to a personal path in the project's gradle.properties | Breaks every other machine and CI | Put it in ~/.gradle/gradle.properties, or export JAVA_HOME in the run script |
| Disabling the configuration cache or Kotlin/Native caches permanently | Slower builds forever for a one-off issue | Treat as a temporary workaround; record why |
Adding OTHER_LDFLAGS in the app for a library problem | Every consumer must repeat it | Fix in the library's package (linkerSettings) or Gradle config |
Removing iosX64 to speed up builds | Intel-hosted simulators and CI lose the module | Keep it when anyone runs x86_64 simulators |
Related skills
kmp-xcframework-distribution— XCFramework, SPMbinaryTarget, linker settings for consumers.kmp-swiftui-interop— Swift-side API problems once the build is green.kmp-build-check— the both-platform build and test matrix after the fix.kmp-gradle-version-catalog— aligning Kotlin, Compose Multiplatform, AGP, KSP and SKIE versions.kmp-expect-actual— designing the platform split when an expect/actual error is really a design problem.kmp-crash-triage— crashes that are not caused by build configuration.kmp-ci-github-actions— failures that only happen on CI runners.- Kotlin agent skills — including the AGP 9 migration and Kotlin/Native build performance skills.
- MobileBuildMCP (formerly XcodeBuildMCP) — structured Xcode build and simulator access for agents.
- Docs: KMP compatibility guide, Compose Multiplatform compatibility, Kotlin/Native compilation time.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

