Capacitor 8 Android Requirements: Java, SDK, Gradle and AGP

The documented Capacitor 8 baseline

The official Android migration section specifies these settings for the 7 → 8 transition. Reviewed 2 October 2026; check later 8.x release notes before selecting an exact release.

These are a migration baseline, not evidence that all plugins accept the combination. A library can impose a higher minimum or another constraint. Keep the chosen versions together in the migration record.

Java 21 guidance is not the AGP minimum

Capacitor's plugin migration guidance recommends Java 21 and shows source/target compatibility set to 21; it also says Java 17+ is supported. Meanwhile, AGP 8.13's compatibility table lists JDK 17 as its minimum/default runtime.

Do not turn AGP's minimum into a claim that JDK 17 can compile every Capacitor 8 application. Code or a dependency targeting Java 21 needs an appropriate compiler/toolchain. Use JDK 21 as the practical migration baseline unless you have verified the lower-JDK combination for your exact project.

java -version
cd android
./gradlew --version

Compare the wrapper's JVM with Android Studio's Gradle JDK and the CI runner. Check JAVA_HOME, org.gradle.java.home and any declared Java toolchain. A correct terminal JDK does not prove that the IDE builds with it.

Android's Java-version guidance separates the JVM running Gradle from compiler toolchains and language/bytecode targets. Keep those settings aligned; lowering a source target to silence an error can obscure the actual dependency requirement.

SDK 36 does not mean Build Tools 36

The AGP 8.13 table lists Gradle 8.13 as its minimum/default and SDK Build Tools 35.0.0 as its minimum/default. Capacitor's migration uses wrapper 8.14.3. These values answer different questions, so they need not be identical.

Install the SDK platform needed for compile SDK 36. Inspect an explicit buildToolsVersion pin before changing it; do not invent a Capacitor requirement for Build Tools 36. If there is no pin, inspect the tool version selected by the build. Use the SDK Manager and build output to confirm what is present.

Build Tools, platform-tools, the Android platform SDK and the NDK are separate packages. A native C/C++ plugin may add an NDK constraint; this guide does not assign one to every Capacitor app.

Inspect an older project's actual files

1. Check android/variables.gradle and app-level overrides for the three SDK values. In custom projects, also inspect version catalogs and plugin-management blocks.
2. Locate the AGP declaration in the root build configuration, then the distribution URL in gradle/wrapper/gradle-wrapper.properties.
3. Inspect Java compile options and Kotlin JVM targets in app and custom plugin modules.
4. Compare AndroidX and Google-service dependencies with the official migration diff where used.
5. Review manifests, custom activities, flavors, signing configuration and CI images before synchronization.

Keep edits targeted. Replacing the entire Android folder can discard product-specific source and settings. For a project starting on Capacitor 6, use the 6 → 7 → 8 sequence rather than updating only final SDK values.

Treat target SDK changes as runtime work

A higher compile SDK makes APIs available to the compiler; target SDK changes the compatibility behavior your app opts into. A higher minimum SDK changes which devices can install it. Document the supported-device decision before applying a minimum bump.

Review Android 16 behavior changes for targeted apps against your own features. Check edge-to-edge layout, system bars, keyboard insets, navigation and any native permissions or background work used by plugins. Test both your minimum supported OS and a current OS; a screenshot in one emulator is not enough for those behaviors.

Interpret common failures by layer

• AGP unsupported by Studio: compare IDE/AGP compatibility before changing the application.
• Invalid source release / unsupported class version: compare Gradle JVM, compiler toolchain and bytecode targets.
• AAR metadata says compile SDK is too low: locate the dependency and compare its requirement with the app setting.
• Manifest merge or duplicate classes: inspect plugin contributions and dependency resolution; the SDK bump may only expose an older conflict.
• Build passes, screen is clipped: investigate layout/inset behavior, not npm resolution.

After the production web build and npx cap sync android, inspect changes and run ./gradlew assembleDebug from android/. Record the JVM and resolved versions with the result, then test real plugin paths using the compatibility checklist.