Flutter Android build stops with Execution failed for task ':app:…'
Execution failed for task ':app:checkDebugAarMetadata'.Short answer
The line only tells you which Gradle step broke; the task name in the quotes tells you why. checkAarMetadata means compileSdk or AGP is too old for a library, MinSdkCheck and mergeDex point at minSdk, compileFlutterBuild is a Dart error, and compileKotlin or a Java message means the toolchain versions disagree. Find the first 'What went wrong' block and use the matching section below.
Fix it fast
1Find out which cause you have
Rebuild with verbose output and print only the failure blocks. The task in the first one is the real failure; later ones often follow from it.
flutter build apk --debug -v 2>&1 | grep -n -A15 "What went wrong"2Match what you see, then jump to its fix
- 1
Dependency '…' requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs.checkDebugAarMetadata: a library needs a newer compileSdk or AGPFix - 2
Error: Your project's minimum Android SDK version (…) is lower than Flutter's minimum supported version of …, or uses-sdk:minSdkVersion 21 cannot be smaller than version 24 declared in library [:some_plugin]MinSdkCheck, processManifest or mergeDex: minSdk is too lowFix - 3
Process 'command '…/flutter/bin/flutter'' finished with non-zero exit value 1compileFlutterBuildDebug or Release: the Dart side did not compileFix - 4
Android Gradle plugin requires Java 17 to run, Unsupported class file major version 65, or Error: Your project's Android Gradle Plugin version (…) is lower than Flutter's minimum supported version of …Java, Gradle and the Android Gradle Plugin do not matchFix - 5
was compiled with an incompatible version of Kotlin, or The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0compileReleaseKotlin or plugin setup: Kotlin versions and AGP 9Fix
- 1
What does the error look like?
Execution failed for task ':app:checkDebugAarMetadata'.Execution failed for task ':app:compileFlutterBuildRelease'.Execution failed for task ':app:mergeDexRelease'.Execution failed for task ':app:compileReleaseKotlin'.Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
Cause 1 of 5
checkDebugAarMetadata: a library needs a newer compileSdk or AGP
1Check
AndroidX and plugin libraries record the lowest compileSdk and Android Gradle Plugin they accept. The message names the library, the level it wants and the level your app compiles with. A compileSdk typed as a number years ago is the usual reason; the other variant says a dependency requires a newer Android Gradle plugin.
grep -n "compileSdk" android/app/build.gradle*2Fix
Let Flutter manage compileSdk (it is 36 on current stable) or set the number the message asks for. Your AGP must support that level: Android's table lists 8.9.1 as the minimum for API 36 and 9.1.1 for API 37. compileSdk only decides which APIs you can call; it does not change runtime behaviour the way targetSdk does.
// android/app/build.gradle.kts
android {
compileSdk = flutter.compileSdkVersion
ndkVersion = flutter.ndkVersion
}3Verify
Run the same task on its own from the android folder.
cd android && ./gradlew :app:checkDebugAarMetadataCause 2 of 5
MinSdkCheck, processManifest or mergeDex: minSdk is too low
1Check
Flutter's Gradle plugin adds a per-variant check (for example ReleaseMinSdkCheck) that fails when minSdk is below what your Flutter release supports; current Flutter supports API 24 and up. A plugin can also demand a higher minSdk, which the manifest merger reports. Old projects that still sit below API 21 hit the 64K method limit in the dex step instead, because multidex is only automatic from API 21.
grep -n "minSdk" android/app/build.gradle*2Fix
Use Flutter's default minSdk, or the higher number a plugin asks for. Once minSdk is 21 or more, you can delete multiDexEnabled and the androidx.multidex dependency, since the runtime loads several dex files on its own.
// android/app/build.gradle.kts
defaultConfig {
minSdk = flutter.minSdkVersion
targetSdk = flutter.targetSdkVersion
}3Verify
The check task passes and a release build gets past the dex step.
flutter build apk --releaseCause 3 of 5
compileFlutterBuildDebug or Release: the Dart side did not compile
1Check
This task runs Flutter's own build of your Dart code and assets; Gradle only reports that the flutter command exited with an error. The useful lines are printed above the Gradle block: Dart compile errors with file and line, a missing asset, or a package that does not support your Dart version. One failure that only shows in release builds comes from icon tree shaking, which needs every IconData to be a constant.
flutter analyze
flutter build apk --release 2>&1 | grep -n -B2 -A6 "Error:"2Fix
Fix the first Dart error shown, then rebuild. If it says the app cannot tree shake icon fonts, make the listed IconData uses const, or build once with --no-tree-shake-icons to confirm that is the only problem. After a Flutter upgrade, check for packages that need a newer major version.
flutter pub get
flutter pub outdated
flutter build apk --release --no-tree-shake-icons # only to confirm the cause3Verify
flutter analyze reports no errors and the release build completes.
flutter analyze && flutter build apk --releaseCause 4 of 5
Java, Gradle and the Android Gradle Plugin do not match
1Check
Three versions must agree. AGP 8 and 9 need JDK 17 or newer. Gradle must be new enough for that JDK (8.5 for Java 21, 9.1.0 for Java 25) and for the AGP version (AGP 9.3 needs Gradle 9.5.0, AGP 9.4 and 9.5 need 9.6.0). Recent Flutter releases also refuse AGP, Gradle and Kotlin versions below their own minimum and name it in the error. Flutter's Gradle build uses the JDK shown by doctor, not necessarily the one on your PATH.
flutter doctor -v | grep -i -A2 "java binary"
cd android && ./gradlew --version
grep -n "com.android.application" settings.gradle*
grep -n "org.gradle.java.home" gradle.properties2Fix
Point Flutter at a JDK 17 or 21, raise the Gradle wrapper to what your AGP needs, and raise AGP in the plugins block of settings.gradle(.kts) to at least the version Flutter's message names. If the wrapper task itself fails because the old AGP cannot load, edit distributionUrl in gradle/wrapper/gradle-wrapper.properties instead. flutter analyze --suggestions reports the mismatches it can detect. Remove any org.gradle.java.home line that pins an old JDK.
flutter config --jdk-dir="/Applications/Android Studio.app/Contents/jbr/Contents/Home"
cd android && ./gradlew wrapper --gradle-version=9.5.0
// android/settings.gradle.kts
plugins {
id("com.android.application") version "9.3.1" apply false
}3Verify
Gradle prints a supported JVM and the analyzer has no Gradle or Java warnings.
flutter analyze --suggestions
cd android && ./gradlew --versionCause 5 of 5
compileReleaseKotlin or plugin setup: Kotlin versions and AGP 9
1Check
The first message means a library was built with a newer Kotlin than the Kotlin Gradle Plugin your project applies. The second appears after moving to AGP 9, where Kotlin support is built into AGP. Flutter's guidance: since Flutter 3.44, AGP 9 works with android.builtInKotlin=false and android.newDsl=false in gradle.properties (Flutter's migrator adds them on flutter run or build); since 3.47 you may switch built-in Kotlin on once the app and every plugin have migrated; Flutter plans to drop support for applying the Kotlin Gradle Plugin in a future release.
grep -n "kotlin" android/settings.gradle* android/app/build.gradle*
grep -n "builtInKotlin\|newDsl" android/gradle.properties2Fix
On AGP 8, raise the version of org.jetbrains.kotlin.android in settings.gradle(.kts). On AGP 9, follow Flutter's built-in Kotlin migration: keep the two flags, remove the kotlin-android plugin and the kotlinOptions block from the app module, and set the JVM target in a kotlin block.
# android/gradle.properties
android.newDsl=false
android.builtInKotlin=false
// android/app/build.gradle.kts: delete id("kotlin-android") and kotlinOptions { }, then add
kotlin {
compilerOptions {
jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
}
}3Verify
A clean build gets past the Kotlin compile step.
flutter clean && flutter build apk --debugHow do I stop it coming back?
- Keep compileSdk, minSdk, targetSdk and ndkVersion on the flutter.* values unless a plugin forces a number, and leave a comment naming that plugin.
- Upgrade AGP, Gradle and Kotlin in one change, using Android's AGP-to-Gradle table, and build both debug and release before merging.
- Run flutter analyze --suggestions after every Flutter upgrade; it flags Java, Gradle and AGP mismatches before CI does.
- Pin the JDK in CI with flutter config --jdk-dir so builds do not depend on whatever Java the image ships.
Sources
- Android: Android Gradle plugin and Gradle compatibility
- Android: AGP 9.0 release notes
- Gradle: Compatibility matrix
- Android: Enable multidex for apps with over 64K methods
- Flutter: Migrating Android projects to built-in Kotlin
- Flutter: Supported deployment platforms
- Flutter: Build and release an Android app
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Nuclear Home VideoA video-streaming Android app built from scratch, engineered for smooth playback.
Related fixes
Mobile apps
flutter doctor says the Android cmdline-tools component is missing
Android license status unknown.
Flutter checks for a cmdline-tools folder inside the Android SDK it found, and stops the Android checks when that folder is absent.
6 causes, each with a fixMobile apps
Play Console will not accept the release because of its target API level
A target API level warning on the Policy status page, with an extension form link
Since 31 August 2026, Google Play accepts new phone and tablet apps and updates only if they target Android 16 (API level 36); the extension window ran to 1 November 2026.
5 causes, each with a fixMobile apps
Play Console warns the bundle may be obfuscated and has no mapping file
This App Bundle contains Java/Kotlin code, which might be obfuscated.
This warning is about crash reports, not about your release being blocked.
3 causes, each with a fixMobile apps
AGP 9 marks the android block as deprecated or fails on BaseExtension
java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated cannot be cast to class com.android.build.gradle.BaseExtension
AGP 9.0 uses only the new public DSL interfaces.
3 causes, each with a fixMobile apps
The editor cannot find R, so every R.string and R.id turns red
Unresolved reference: R
R is a class that the build generates from your res folder, in the package named by the module's namespace.
4 causes, each with a fixMobile apps
Android Studio says it could not identify the launch activity when you press Run
Run > Edit Configurations > Launch Options is set to Nothing or to a class that no longer exists
Android Studio launches the activity marked with a MAIN action and a LAUNCHER category in the merged manifest.
3 causes, each with a fix