Fix Gradle and Java Version Mismatch in Flutter

Problem Statement

When updating Android Studio, many Flutter developers encounter a critical build failure due to incompatibility between their project's Gradle version and the Java version used by Android Studio. This mismatch typically generates the error:

FAILURE: Build failed with an exception.
* What went wrong: Could not open settings generic class cache for settings file...
> BUG! exception in phase 'semantic analysis' in source unit 'BuildScript' 
  Unsupported class file major version 61

This occurs because:

• Older Gradle versions (like 6.8.3) don't support newer Java versions (e.g., Java 17+)
• Android Studio updates often bundle newer Java runtimes, causing version conflicts
• Flutter projects may inherit incompatible Gradle configurations from templates

Solutions

Choose one of these verified approaches based on your project constraints:

---

✅ Solution 1: Upgrade Gradle (Recommended)

Update your Gradle version to match your Java version using the official compatibility matrix:

1. Check your Java version:

   java --version

   Identify major version:

   • Java 17 → Major version 61
   • Java 21 → Major version 65

2. Update gradle-wrapper.properties:
   Open android/gradle/wrapper/gradle-wrapper.properties and modify distributionUrl per Gradle Compatibility Table:

   # For Java 17
   distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-all.zip
   
   # For Java 21 (required by Android Studio 2024.2+)
   distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip

3. Update Android Gradle Plugin in android/build.gradle:

   dependencies {
   -    classpath "com.android.tools.build:gradle:4.1.0"
   +    classpath "com.android.tools.build:gradle:8.3.2" // Match Gradle version
   }

4. Update JDK targets in android/app/build.gradle:

   android {
     compileOptions {
   -    sourceCompatibility JavaVersion.VERSION_11
   -    targetCompatibility JavaVersion.VERSION_11
   +    sourceCompatibility JavaVersion.VERSION_17
   +    targetCompatibility JavaVersion.VERSION_17
     }
     kotlinOptions {
   -    jvmTarget = "11"
   +    jvmTarget = "17"
     }
   }

5. Clean and rebuild:

   flutter clean && flutter pub get

---

🏠 Solution 2: Configure JDK Home Path

If upgrading isn't feasible, direct Flutter to a compatible JDK:

1. Locate JDK path:

   # macOS/Linux
   /usr/libexec/java_home -v 11 # Adjust version
   
   # Windows: Typical paths
   # "C:\Program Files\Java\jdk-11.x.x"

2. Set Flutter JDK path:

   flutter config --jdk-dir /path/to/compatible/jdk
   # Example:
   flutter config --jdk-dir "/usr/lib/jvm/java-11-openjdk-amd64"

3. Verify configuration:

   flutter doctor -v
   # Look for "Java version" in output

---

⚙️ Solution 3: Configure Project-Specific Java Home

Set a Java home path directly in Gradle properties:

1. Add to gradle.properties:

   org.gradle.java.home=/path/to/compatible/jdk
   # Example for Java 11:
   org.gradle.java.home=/usr/lib/jvm/java-11-openjdk-amd64

2. Sync and restart IDE:

   • File > Invalidate Caches / Restart in Android Studio
   • Re-run your build

---

Key Compatibility Guide

Java Version	Min Gradle	Min Android Gradle Plugin
Java 11	7.0+	7.0+
Java 17	7.3+	7.4+
Java 21	8.5+	8.3.2+

TIP

Always validate compatibility:

1. Gradle-Java Matrix
2. Android Plugin-Gradle Compatibility

Preventing Future Issues

1. Before updating Android Studio:
   • Check current Java version (java --version)
   • Verify Gradle compatibility proactively
2. Create version markers:

   # In project root
   echo "javaVersion=17" > .flutter_settings
   echo "gradleVersion=8.5" >> .flutter_settings

WARNING

Never force legacy Gradle versions to use unsupported Java - this causes unstable builds and hidden errors.

Troubleshooting Steps

Use this sequence if solutions above fail:

flutter clean
sudo rm -rf android/build android/.gradle
flutter pub upgrade --major-versions
flutter run --verbose # Examine specific errors