Android development / Editorial solution guide

Diagnose Gradle and JDK compatibility failures

Separate the JDK running Gradle from compilation targets and repair a mismatched toolchain using the project’s actual compatibility requirements.

About 3 min readContent reviewed 2026-10-23

Read-only knowledge base · No public comments

Recognize the symptoms

Synchronization or a build fails before application code runs. The error may mention an unsupported class-file version, an incompatible Java runtime, or a required Gradle version. Studio may succeed while a terminal fails, or the reverse. Record the exact first relevant message and whether the failure occurs during plugin loading, script evaluation, or Kotlin compilation.

Understand the likely causes

Studio can run Gradle with its configured Gradle JDK, while a terminal can use JAVA_HOME or the java executable on PATH. The wrapper selects Gradle, and the Android Gradle plugin imposes its own compatibility requirements. Java source compatibility and Kotlin JVM target settings control emitted code; changing them does not necessarily change the runtime that is already executing Gradle.

Identify the runtime actually in use

Inspect the project wrapper configuration, plugin declarations or version catalog, Studio’s Gradle JDK selection, and the CI Java setup. Compare these as one set rather than asking which Java version is universally newest. The commands below report the terminal environment and wrapper-selected build runtime. Run them only in the intended checked-out project; an uncached wrapper may download its configured distribution. Keep paths or environment details private when sharing a report, and never paste the complete environment with credentials.

bash Read the selected Java and Gradle runtime versions

java -version
./gradlew --version

These are diagnostic commands for an existing trusted Gradle project. They do not install Android SDKs or connect a device. Compare the JVM reported by Gradle with Studio’s configured Gradle JDK; java -version alone is not sufficient evidence.

Read the compatibility row for this plugin

Open the official release documentation for the Android Gradle plugin version declared by the project. Check its required Gradle and JDK versions, then check relevant Kotlin and Compose compiler integration guidance. Do not substitute an arbitrary current version from an unrelated template. If the project uses a newer plugin family with integrated Kotlin support, follow that family’s migration rules rather than adding legacy plugins to silence a symptom. The correction should be a small reviewable configuration change with an identified compatibility reason.

Align the environment before editing source targets

Choose the compatible JDK already supported by the project and configure Studio, terminal sessions, and CI consistently. If the wrapper itself is outside the plugin’s supported range, update it through the documented project workflow together with the affected compatibility settings. Preserve the previous known-good configuration for comparison. Do not begin by deleting caches or rewriting every dependency: those actions remove evidence and do not establish that the runtime can load the plugin. A JVM-target mismatch during compilation is a separate diagnosis from failure to start Gradle.

Verify the fix

Repeat the version report in the terminal and confirm the intended JVM. Synchronize Studio, then run the same project build task and variant that originally failed. Success means the original compatibility message is gone and the intended task reaches completion, not merely that the editor stops underlining a file. Compare CI on the same source revision before declaring the environment repaired.

Keep it from recurring

Document the tested wrapper, plugin, Kotlin/Compose integration, and JDK as a compatible set. Review upgrades together and retain a minimal reproducible failing command in bug reports. Avoid machine-specific JDK paths in shared configuration unless the project explicitly manages them.