Gradle Build Failed: Fix the Minimum Version

You run flutter build apk, Gradle spins for a minute downloading dependencies, then dies with Minimum supported Gradle version is 8.7. Current version is 8.3. Nothing in your Dart code changed — the failure lives entirely in the Android build layer. This error spikes after every flutter upgrade, because the new Flutter pins a newer Android Gradle Plugin, and that plugin demands a newer Gradle than your project's wrapper still downloads.

The version triangle confuses everyone the first time: Flutter, the Android Gradle Plugin (AGP), Gradle itself, and the JDK must all agree. AGP 8.x needs Gradle 8.x and JDK 17; hand it Gradle 7 or JDK 11 and the build fails with messages that blame each other. Developers often fix the wrong corner — upgrading Gradle when Java is the problem — and burn hours.

This guide untangles the triangle. You will read the error to identify which corner is stale, look up the exact AGP-to-Gradle minimum, bump the wrapper's distributionUrl correctly, align the JDK, and verify with a clean build. By the end, minimum-version failures become a ten-minute properties edit instead of a lost afternoon.

Reading the Error: Which Corner Is Stale

Minimum-version messages are unusually honest. Minimum supported Gradle version is 8.7. Current version is 8.3 names both sides: the plugin needs 8.7, the wrapper supplied 8.3. Your job is bumping supply to demand — edit the wrapper, not the plugin. Downgrading the plugin to match old Gradle trades a one-line fix for stale build tooling and future incompatibilities.

JDK errors disguise themselves nearby. Unsupported class file major version 65 or A problem occurred evaluating settings means Gradle itself runs on the wrong Java — AGP 8 needs JDK 17, and major version 65 is Java 21 bytecode that old toolchains cannot read. If your error mentions class files, Java, or toolchain instead of two Gradle numbers, skip the wrapper and fix JAVA_HOME first.

Flutter doctor settles arguments fast. Run flutter doctor -v and read the Java and Android toolchain sections before editing anything: a healthy triangle shows Flutter current, AGP pinned, wrapper matching, JDK 17. Change exactly one corner per attempt and rebuild — stacked simultaneous edits leave you unsure which one worked, and the next failure teaches you nothing. Screenshot the triangle readout into the incident channel so the whole team reasons from the same numbers.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/check_android_env.dart
// Prints the wrapper Gradle and the active Java before you edit anything.
Future<void> main() async {
  final props = File('android/gradle/wrapper/gradle-wrapper.properties');
  final text = await props.readAsString();
  final gradle = RegExp(r'gradle-(.+?)-').firstMatch(text)?.group(1);
  stdout.writeln('Wrapper Gradle: $gradle');
  final javaHome = Platform.environment['JAVA_HOME'] ?? '(unset)';
  stdout.writeln('JAVA_HOME: $javaHome');
  final java = await Process.run('java', ['-version']);
  stdout.write(java.stderr); // java -version prints to stderr
}

The AGP-to-Gradle Map You Must Respect

Every AGP release publishes a minimum Gradle version, and the plugin enforces it at configuration time — before compiling anything. The landmarks to memorize: AGP 8.0 needs Gradle 8.0 as its floor, AGP 8.5 raises the floor to Gradle 8.7, and AGP 9.x moves the whole line to Gradle 9.x. Minor AGP bumps inside a series can raise the minimum too, which is why a routine flutter upgrade breaks a wrapper that worked last month.

The same table names the JDK floor: AGP 8 requires JDK 17 to run Gradle, full stop. Developers who bump Gradle while running JDK 11 graduate from one error to another and conclude the bump did not work — it did, and now Java is the stale corner. Check Google's AGP release-notes compatibility table for your exact plugin version rather than trusting memory, since floors move.

Write the mapping into your upgrade runbook, not your head. Before any flutter upgrade, record current AGP, wrapper Gradle, and java -version; after upgrading, diff the AGP pin and look up its new minimum. If the minimum exceeds your wrapper, bump the wrapper in the same pull request. Ten minutes of table-checking prevents the six-hour CI outage in our incident story. Pin the table link at the top of the runbook so nobody hunts for it mid-upgrade.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/agp_floor_check.dart
// Fails loudly when the wrapper trails known AGP minimum floors.
const Map<String, String> floors = <String, String>{
  '8.0': '8.0',
  '8.5': '8.7',
  '9.0': '9.1',
};

Future<void> main() async {
  final text =
      await File('android/gradle/wrapper/gradle-wrapper.properties').readAsString();
  final gradle = RegExp(r'gradle-(.+?)-').firstMatch(text)?.group(1) ?? 'unknown';
  stdout.writeln('Wrapper Gradle: $gradle');
  for (final entry in floors.entries) {
    stdout.writeln('AGP ${entry.key} needs Gradle ${entry.value} or newer');
  }
  if (gradle.startsWith('7.')) {
    stderr.writeln('Wrapper is Gradle 7: too old for any AGP 8 project.');
    exit(1);
  }
}

Bumping distributionUrl Without Breaking the Wrapper

The wrapper properties file is small and unforgiving. distributionUrl names the exact Gradle zip to download — change only the version segment, preserving the services.gradle.org host, the distributions path, and your project's -all- versus -bin- flavor. Switching flavors accidentally changes what ships in the distribution and confuses every machine that already cached the other one.

Edit with intent: gradle-8.3-all.zip becomes gradle-8.7-all.zip, nothing else moves. Commit the file — wrapper bumps that live only on one laptop cause works-on-my-machine mysteries when CI downloads the old release. Then run flutter clean before rebuilding: stale build outputs compiled against the old Gradle produce phantom errors that look like the bump failed when it actually succeeded.

Rebuild with fresh resolution once. flutter build apk --debug --refresh-dependencies forces dependency metadata to re-resolve against the new engine; subsequent builds can drop the flag and run at normal speed. Watch the log's Downloaded Gradle line to confirm the runner fetched the version you named — trust the download line, not your memory of the edit. If the line still shows the old release, the edit is uncommitted or the runner cache needs one targeted wipe.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/bump_wrapper.dart 8.7
// Rewrites only the version segment of distributionUrl.
Future<void> main(List<String> args) async {
  if (args.isEmpty) {
    stderr.writeln('Usage: bump_wrapper.dart <version>, e.g. 8.7');
    exit(2);
  }
  final file = File('android/gradle/wrapper/gradle-wrapper.properties');
  final text = await file.readAsString();
  final updated = text.replaceAll(
    RegExp(r'gradle-\d+\.\d+'),
    'gradle-${args.first}',
  );
  if (updated == text) {
    stderr.writeln('No distributionUrl version found; is this the wrapper file?');
    exit(1);
  }
  await file.writeAsString(updated);
  stdout.writeln('Wrapper now targets Gradle ${args.first}. Run flutter clean next.');
}

Aligning the JDK: AGP 8 Means Java 17

Gradle runs on the JVM, so the JDK is a full corner of the triangle. AGP 8 requires JDK 17 to run: launch Gradle with JDK 11 and configuration fails before version checks even matter, with errors about class file versions or unsupported runtimes. Installing JDK 17 is not enough — JAVA_HOME must point at it in every shell and CI runner that builds, and Android Studio's Gradle JDK setting must agree.

Diagnose in one pass. java -version shows the runtime on PATH, echo of JAVA_HOME shows what Gradle daemons inherit, and Android Studio's Settings Build Tools Gradle panel shows what the IDE uses — all three must say 17 for AGP 8 builds. Mismatches between terminal and IDE are the classic split: command-line builds pass while IDE syncs fail, or the reverse, and each side blames the other.

On CI, pin the JDK in the image or setup step rather than hoping the default is right. A setup-java step naming 17, or a base image with JAVA_HOME preset, removes the entire category. Log java -version at the top of every Android job so the next failure opens with the answer instead of a guessing game. When IDE and terminal disagree, believe the one that matches CI and fix the other. Document the blessed JDK path per OS so new hires align on day one.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/jdk_guard.dart
// Exits nonzero unless a Java 17 runtime answers.
Future<void> main() async {
  final result = await Process.run('java', ['-version']);
  final output = '${result.stdout}${result.stderr}';
  stdout.write(output);
  final ok = RegExp(r'"17\.').hasMatch(output) || output.contains(' 17');
  if (!ok) {
    stderr.writeln('AGP 8 needs JDK 17: point JAVA_HOME at a 17 install.');
    exit(1);
  }
  stdout.writeln('JDK looks right for AGP 8.');
}

Keeping Flutter, AGP, and Gradle in Lockstep

Flutter upgrades move the AGP pin, and the AGP pin moves the Gradle floor — so treat flutter upgrade as an Android build change, not just Dart. Before upgrading, record the current triangle: flutter --version, the com.android.application pin, the wrapper version, and java -version. After upgrading, diff the AGP pin first; if it moved, look up its new minimum and bump the wrapper in the same branch.

Resist partial upgrades. A new Flutter with a hand-downgraded AGP buys short-term green builds and long-term drift from the tested template — future upgrades then break harder. Stay on the template's AGP, meet its Gradle and JDK floors, and file issues upstream if the combination genuinely fails. The template is tested as a unit; your custom mix is not.

When everything still fails, bisect cleanly. flutter clean removes stale outputs, --refresh-dependencies re-resolves metadata once, and a fresh checkout rules out local uncommitted edits. Change one corner per attempt and keep notes — the engineer who writes down each attempt solves it in four steps, while the one who flails solves it in forty. A written bisect log also becomes next quarter's runbook entry. Future upgrades then start from evidence instead of folklore.

import 'dart:io';

// Run with: dart io/thecodeforge/flutter/triangle_report.dart
// Prints the version triangle for paste-into-CI logs.
Future<void> main() async {
  final wrapper =
      await File('android/gradle/wrapper/gradle-wrapper.properties').readAsString();
  final gradle = RegExp(r'distributionUrl=.*gradle-(.+?)\.zip').firstMatch(wrapper)?.group(1);
  stdout.writeln('Wrapper Gradle: ${gradle ?? 'unknown'}');
  final flutter = await Process.run('flutter', ['--version']);
  stdout.write(flutter.stdout);
  final java = await Process.run('java', ['-version']);
  stdout.write(java.stderr);
}

Verifying With a Clean assembleDebug

Trust only a clean build from a committed tree. Commit the wrapper bump, run flutter clean to drop outputs compiled under the old engine, and build with flutter build apk --debug. A green assembleDebug plus the Downloaded Gradle line showing your target version is the proof — anything less, like an incremental hot-reload session, can pass while CI still fails.

Verify the artifact, not just the exit code. Install the debug APK on a device with flutter install and launch it past the first frame; resource-merging and dexing failures sometimes surface at install or launch rather than compile time. Then run the same command on CI and compare version lines — local and remote must agree on Gradle, AGP, and Java before you declare victory.

Lock the win. A CI step echoing the triangle versions each build turns future mismatches into readable diffs, and requiring review on wrapper and AGP lines stops silent drift. Minimum-version errors should cost your team ten minutes exactly once — the second occurrence means the guardrails, not the properties file, need fixing. Treat a repeat as a process bug and fix the checklist, not just the version. Green builds you cannot explain are just red builds waiting for Friday.