spring-projects/spring-boot · critical · GradleException

Spring Boot plugin requires Gradle 8.x (8.14 or later) or 9.

Error message

Spring Boot plugin requires Gradle 8.x (8.14 or later) or 9.x. The current version is {}

What it means

Thrown by SpringBootPlugin.verifyGradleVersion() during plugin application if GradleVersion.current() is older than 8.14. It is a hard fail (GradleException) at apply() time, so no Spring Boot tasks are registered. The message explicitly states the supported range (8.x at 8.14+, or 9.x).

Source

Thrown at build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/plugin/SpringBootPlugin.java:129

	/**
	 * The coordinates {@code (group:name:version)} of the
	 * {@code spring-boot-dependencies} bom.
	 */
	public static final String BOM_COORDINATES = "org.springframework.boot:spring-boot-dependencies:"
			+ SPRING_BOOT_VERSION;

	@Override
	public void apply(Project project) {
		verifyGradleVersion();
		createExtension(project);
		Configuration bootArchives = createBootArchivesConfiguration(project);
		registerPluginActions(project, bootArchives);
	}

	private void verifyGradleVersion() {
		GradleVersion currentVersion = GradleVersion.current();
		if (currentVersion.compareTo(GradleVersion.version("8.14")) < 0) {
			throw new GradleException("Spring Boot plugin requires Gradle 8.x (8.14 or later) or 9.x. "
					+ "The current version is " + currentVersion);
		}
	}

	private void createExtension(Project project) {
		project.getExtensions().create("springBoot", SpringBootExtension.class, project);
	}

	private Configuration createBootArchivesConfiguration(Project project) {
		Configuration bootArchives = project.getConfigurations().create(BOOT_ARCHIVES_CONFIGURATION_NAME);
		bootArchives.setDescription("Configuration for Spring Boot archive artifacts.");
		bootArchives.setCanBeResolved(false);
		return bootArchives;
	}

	private void registerPluginActions(Project project, Configuration bootArchives) {
		SinglePublishedArtifact singlePublishedArtifact = new SinglePublishedArtifact(bootArchives,
				project.getArtifacts());

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Upgrade the Gradle wrapper to 8.14+ (or 9.x): ./gradlew wrapper --gradle-version 8.14.
2. If a system Gradle is used in CI/Docker, install Gradle >= 8.14.
3. Align IDE Gradle distribution with the wrapper (Settings > Gradle > Use Gradle from: gradle-wrapper.properties).
4. If you cannot upgrade Gradle, downgrade Spring Boot to a version whose minimum matches your Gradle.

Example fix

// before: gradle/wrapper/gradle-wrapper.properties
//   distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip
// after:
//   distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip
// or run:
//   ./gradlew wrapper --gradle-version 8.14

// Fail fast with a clear message before applying the plugin
import org.gradle.util.GradleVersion

if (GradleVersion.current() < GradleVersion.version("8.14")) {
    throw GradleException("Spring Boot requires Gradle 8.14+. Current: ${GradleVersion.current()}")
}
project.pluginManager.apply("org.springframework.boot")

When it happens

Trigger: Applying the Spring Boot plugin (plugins { id 'org.springframework.boot' }) calls apply() -> verifyGradleVersion(); GradleVersion.current().compareTo(GradleVersion.version("8.14")) < 0 throws at line 129.

Common situations: Upgrading Spring Boot to a version that raised the Gradle floor without upgrading the wrapper; CI using a system Gradle older than the wrapper; IDE-bundled Gradle older than 8.14; a Docker build image with an old Gradle.

Related errors

• Failed to set file mode on CopySpec
• Failed to get dir mode from CopySpec
• Failed to get file mode from CopySpec
• Failed to get mode from FileCopyDetails
• Failed to read '{}'

AI-assisted analysis of spring-projects/spring-boot@5b2dbdbb8b (2026-08-04). Data as JSON: /data/errors/a56e1a4f23eb225c.json. Report an issue: GitHub.