Android Java Gradle migration guide

Summary

#

If you've recently upgraded Android Studio to the Flamingo release and have either run or built an existing Android app, you might have run into an error similar to the following:

Error dialog in Android Studio Flamingo: MultipleCompilationErrorsException

The terminal output for this error is similar to the following:

sh
FAILURE: Build failed with an exception.

* Where:
Build file '…/example/android/build.gradle'
* What went wrong:
Could not compile build file '…/example/android/build.gradle'.
> startup failed:
  General error during conversion: Unsupported class file major version 61

  java.lang.IllegalArgumentException: Unsupported class file major version 61
  	at groovyjarjarasm.asm.ClassReader.<init>(ClassReader.java:189)
  	at groovyjarjarasm.asm.ClassReader.<init>(ClassReader.java:170)
  	[…

209 more lines of Groovy and Gradle stack trace …

  	 …]
  	at java.base/java.lang.Thread.run(Thread.java:833)

This error occurs because Android Studio Flamingo updates its bundled Java SDK from 11 to 17. Flutter uses the version of Java bundled with Android Studio to build Android apps. Gradle versions prior to 7.3 can't run when using Java 17.

You can fix this error by upgrading your Gradle project to a compatible version (7.3 through 7.6.1, inclusive) using one of the following approaches.

Solution #1: Guided fix using Android Studio

#

Upgrade the Gradle version in Android Studio Flamingo as follows:

  1. In Android Studio, open the android folder. This should bring up the following dialog:

    Dialog prompting you to upgrade Gradle

    Update to a Gradle release between 7.3 through 7.6.1, inclusive.

  2. Follow the guided workflow to update Gradle.

    Workflow to upgrade Gradle

Solution #2: Manual fix at the command line

#

Do the following from the top of your Flutter project.

  1. Go to the Android directory for your project.

    cd android
  2. Update Gradle to the preferred version. Choose between 7.3 through 7.6.1, inclusive.

    ./gradlew wrapper --gradle-version=7.6.1

Notes

#

A few notes to be aware of:

  • Repeat this step for each affected Android app.
  • This issue can be experienced by those who don't download Java and the Android SDK through Android studio. If you've manually upgraded your Java SDK to version 17 but haven't upgraded Gradle, you can also encounter this issue. The fix is the same: upgrade Gradle to a release between 7.3 and 7.6.1.
  • Your development machine might contain more than one copy of the Java SDK:
    • The Android Studio app includes a version of Java, which Flutter uses by default.
    • If you don't have Android Studio installed, Flutter relies on the version defined by your shell script's JAVA_HOME environment variable.
    • If JAVA_HOME isn't defined, Flutter looks for any java executable in your path. Once issue 122609 lands, the flutter doctor command reports which version of Java is used.
  • If you upgrade Gradle to a release newer than 7.6.1, you might (though it's unlikely) encounter issues that result from changes to Gradle, such as deprecated Gradle classes, or changes to the Android file structure, such as splitting out ApplicationId from PackageName. If this occurs, downgrade to a release of Gradle between 7.3 and 7.6.1, inclusive.
  • Upgrading to Flutter 3.10 won't fix this issue.