OtaKitHow to resolve Android build errors in Capacitor
Gradle failures, SDK mismatches, manifest merger conflicts, duplicate classes — the Android build errors that hit Capacitor apps most, and a repeatable way to diagnose and fix each one.
Android build failures in Capacitor tend to look scarier than they are. The error text is a wall of Gradle output, but the actual cause is almost always one of a handful of usual suspects. This guide is a triage checklist: the most common Capacitor Android build errors and a repeatable way to fix each one.
First move, every time: read the first error, not the last. Gradle prints a cascade, and the root cause is near the top. Then run ./gradlew assembleDebug --stacktrace from the android/ folder for the real message.
1. Version mismatch
Misaligned Capacitor core/CLI/plugins is the most common hidden cause. Rule it out first with npx cap doctor — see fixing version mismatch.
2. Manifest merger conflicts
Two plugins declaring incompatible manifest attributes (min SDK, a permission, an activity) fail the merge. The error names the conflicting nodes — resolve with a tools:replaceor by aligning the plugins.
3. Duplicate classes
Two dependencies bundling the same class (often an old support lib vs AndroidX). Find the duplicate with a dependency tree and exclude the stale one:
./gradlew app:dependencies | grep -i theclass
4. SDK / build-tools not installed
A compileSdk or build-tools version your machine doesn't have. Install it via the SDK manager, or align compileSdk to a version you do have. This one bites CI constantly — the runner image lacks the SDK you assume.
5. AGP / Gradle incompatibility
The Android Gradle Plugin and Gradle wrapper versions have to be compatible. A bump to one without the other fails immediately — and AGP 9 in particular introduced new requirements, covered in AGP 9 build errors.
The reset that fixes a surprising amount
cd android && ./gradlew clean rm -rf ~/.gradle/caches # nuclear option for corrupt caches cd .. && npx cap sync
Reproduce CI failures locally by matching the CI's JDK and SDK versions. Half of “works locally, fails in CI” Android errors are just a different JDK or missing SDK package on the runner.
Where to go next
See building Android in GitHub Actions for a reference CI setup and Setup for the baseline project config.