/gradle-build

description: Fix Gradle build errors for Android and KMP projects

Gradle Build Fix

Incrementally fix Gradle build and compilation errors for Android and Kotlin Multiplatform projects.

Step 1: Detect Build Configuration

Identify the project type and run the appropriate build:

| Indicator | Build Command | |-----------|---------------| | `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` | | `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` | | `settings.gradle.kts` with modules | `./gradlew assemble 2>&1` | | Detekt configured | `./gradlew detekt 2>&1` |

Also check `gradle.properties` and `local.properties` for configuration.

Step 2: Parse and Group Errors

1. Run the build command and capture output 2. Separate Kotlin compilation errors from Gradle configuration errors 3. Group by module and file path 4. Sort: configuration errors first, then compilation errors by dependency order

Step 3: Fix Loop

For each error:

1. **Read the file** — Full context around the error line 2. **Diagnose** — Common categories:

• Missing import or unresolved reference
• Type mismatch or incompatible types
• Missing dependency in `build.gradle.kts`
• Expect/actual mismatch (KMP)
• Compose compiler error

3. **Fix minimally** — Smallest change that resolves the error 4. **Re-run build** — Verify fix and check for new errors 5. **Continue** — Move to next error

Step 4: Guardrails

Stop and ask the user if:

• Fix introduces more errors than it resolves
• Same error persists after 3 attempts
• Error requires adding new dependencies or changing module structure
• Gradle sync itself fails (configuration-phase error)
• Error is in generated code (Room, SQLDelight, KSP)

Step 5: Summary

Report:

• Errors fixed (module, file, description)
• Errors remaining
• New errors introduced (should be zero)
• Suggested next steps

Common Gradle/KMP Fixes

| Error | Fix | |-------|-----| | Unresolved reference in `commonMain` | Check if the dependency is in `commonMain.dependencies {}` | | Expect declaration without actual | Add `actual` implementation in each platform source set | | Compose compiler version mismatch | Align Kotlin and Compose compiler versions in `libs.versions.toml` | | Duplicate class | Check for conflicting dependencies with `./gradlew dependencies` | | KSP error | Run `./gradlew kspCommonMainKotlinMetadata` to regenerate | | Configuration cache issue | Check for non-serializable task inputs |

Navigation

• [Command → Agent / Skill Map](../docs/COMMAND-AGENT-MAP.md)
• [Agents index](../AGENTS.md)
• [Contexts directory](../contexts)
• [Contributing guide](../CONTRIBUTING.md)