spring-projects/spring-boot · error · IllegalStateException

Docker API version must be at least

Error message

Docker API version must be at least %s to support this feature, but current API version is %s

What it means

DockerApi.buildUrl(Feature, ...) negotiates the Docker engine API version against the minimum required by the requested Feature. If the running daemon's version is older than feature.minimumVersion() (and not the UNKNOWN_API_VERSION sentinel), the operation is unsupported and the plugin throws IllegalStateException naming both the required and the current version.

Solutions

1. Upgrade Docker engine to a version supporting the required API (check 'docker version' Server API version)
2. Use a CI runner image with a newer Docker daemon
3. Replace podman/compatibility shim with a real Docker daemon if API coverage is missing

ApiVersion current = docker.getApiVersion();
if (current.compareTo(feature.minimumVersion()) < 0) {
    throw new IllegalStateException("Docker daemon too old: need " + feature.minimumVersion() + ", have " + current);
}

try { docker.buildUrl(feature, path); } catch (IllegalStateException ex) { log.error("Upgrade Docker daemon -- feature requires a newer API"); throw ex; }

When it happens

Trigger: Invoking buildpack features that require a newer Docker API than the running daemon provides (e.g. PLATFORM_IMAGE_PULL requires 1.41).

Common situations: Old Docker daemon on a CI runner; podman/docker-compatible engines with limited API coverage; enterprise-locked Docker versions; outdated Docker Desktop.

Related errors

• Connection to the Docker daemon at
• Docker API call to ' ' failed with status code
• Docker context ' ' does not exist
• Error adding certificates to KeyStore
• Error creating Docker registry authentication header

AI-assisted analysis of spring-projects/spring-boot@270dfe353f (2026-08-11). Data as JSON: /api/errors/d3a3f9eb92952038. Report an issue: GitHub.

Appendix: source

Thrown at buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/DockerApi.java:151

	private URI buildUrl(String path, @Nullable Collection<?> params) {
		return buildUrl(Feature.BASELINE, path, (params != null) ? params.toArray() : null);
	}

	private URI buildUrl(String path, Object... params) {
		return buildUrl(Feature.BASELINE, path, params);
	}

	URI buildUrl(Feature feature, String path, Object @Nullable ... params) {
		ApiVersion version = getApiVersion();
		if (version.equals(UNKNOWN_API_VERSION) || (version.compareTo(PREFERRED_API_VERSION) >= 0
				&& version.compareTo(feature.minimumVersion()) >= 0)) {
			return buildVersionedUrl(PREFERRED_API_VERSION, path, params);
		}
		if (version.compareTo(feature.minimumVersion()) >= 0) {
			return buildVersionedUrl(version, path, params);
		}
		throw new IllegalStateException(
				"Docker API version must be at least %s to support this feature, but current API version is %s"
					.formatted(feature.minimumVersion(), version));
	}

	private URI buildVersionedUrl(ApiVersion version, String path, Object @Nullable ... params) {
		try {
			URIBuilder builder = new URIBuilder("/v" + version + path);
			if (params != null) {
				int param = 0;
				while (param < params.length) {
					builder.addParameter(Objects.toString(params[param++]), Objects.toString(params[param++]));
				}
			}
			return builder.build();
		}
		catch (URISyntaxException ex) {
			throw new IllegalStateException(ex);
		}

View on GitHub (pinned to 270dfe353f)