Flutter Gradle and JDK Compatibility: A Faster Debugging Path
Flutter Android builds often fail in Gradle output long after the real JDK mismatch was introduced. Separate the toolchain versions before changing dependencies.
Read the version boundary first
A Flutter build is a chain, not one compiler. Flutter invokes a Gradle wrapper, the wrapper runs on a JDK, the Android Gradle Plugin targets an Android build toolchain, and the project may compile Kotlin or Java code with its own settings. A failure in one layer can surface as an unhelpful task name in another.
Start by collecting the versions without changing anything:
flutter --version
flutter doctor -v
java -version
echo "$JAVA_HOME"
cd android
./gradlew --version
./gradlew help --stacktraceThe Gradle report is particularly useful because it says which JVM actually launched Gradle. java -version from your shell can disagree with the JVM selected by Android Studio or a Flutter invocation.
Classify the first failure
If the output contains Unsupported class file major version, suspect that the JDK is newer than a Gradle component can understand, or that a plugin was compiled for a newer JDK than the current one. If it contains Could not determine the dependencies and then a Java or Kotlin target mismatch, inspect sourceCompatibility, targetCompatibility, and Kotlin jvmTarget before changing a dependency.
If the failure is Could not resolve with repository or timeout details, do not treat it as a JDK problem. If it says an Android SDK component or license is missing, fix the SDK installation path first. The visible failing task is often downstream from the missing prerequisite.
Make the chosen JDK explicit
On macOS, inspect installed JDKs rather than assuming the first one on PATH:
/usr/libexec/java_home -V
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
cd android && ./gradlew --versionUse the JDK version supported by the project Gradle and Android Gradle Plugin combination. Do not blindly select the newest JDK because it is installed. Conversely, do not downgrade a build until you know which component rejects the current version.
After changing the environment, clear only the cache that is relevant to the evidence. Re-run ./gradlew --version and the smallest failing task before deleting the entire Flutter or Gradle cache. A full cache deletion hides useful signals and turns a compatibility issue into a slow download issue.
The Flutter Doctor Log Diagnoser groups common signatures from pasted output. It is deliberately a text triage aid, not a replacement for checking the actual Gradle report.