spring-projects/spring-boot · error · GradleException

Invalid Docker configuration, either context or host can be…

Error message

Invalid Docker configuration, either context or host can be provided but not both

What it means

Thrown by DockerSpec.customizeHost when both 'context' and 'host' are set on the Docker configuration. These are mutually exclusive ways to locate the Docker daemon: 'context' references a named Docker context, 'host' specifies a direct host URL. The plugin detects both being non-null and rejects the configuration before attempting to connect.

Solutions

Choose one: set either docker.context OR docker.host, not both.
If you switched to using a Docker context, remove the docker.host line.
If you switched to a direct host, remove the docker.context line.
Verify no environment variable (DOCKER_HOST) is implicitly setting host while you also set context in DSL.

Example fix

// before
tasks.bootBuildImage {
    docker {
        context = "remote"
        host = "tcp://docker.example.com:2375"  // throws: both set
    }
}
// after
tasks.bootBuildImage {
    docker {
        host = "tcp://docker.example.com:2375"
    }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate mutual exclusivity before the task runs.
String ctx = dockerSpec.getContext().getOrNull();
String host = dockerSpec.getHost().getOrNull();
if (ctx != null && host != null) {
    throw new GradleException("Set either context OR host, not both.");
}

Prevention

Set either docker.context or docker.host, never both.
When switching connection methods, unset the old property.
Check for DOCKER_HOST environment variable that may implicitly set host alongside a DSL context.

When it happens

Trigger: Configuring bootBuildImage (or related Docker-using tasks) with both docker.context and docker.host set simultaneously in the DSL, e.g. docker { context = 'my-context'; host = 'tcp://docker:2375' }.

Common situations: Switching from a direct host connection to a Docker context (or vice versa) and forgetting to unset the old property. Copying example DSL that sets both. CI configs that set DOCKER_HOST as well as a context.

Related errors

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

Appendix: source

Thrown at build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/tasks/bundling/DockerSpec.java:136

	 * Returns this configuration as a {@link BuilderDockerConfiguration} instance. This
	 * method should only be called when the configuration is complete and will no longer
	 * be changed.
	 * @return the Docker configuration
	 */
	BuilderDockerConfiguration asDockerConfiguration() {
		BuilderDockerConfiguration dockerConfiguration = new BuilderDockerConfiguration();
		dockerConfiguration = customizeHost(dockerConfiguration);
		dockerConfiguration = dockerConfiguration.withBindHostToBuilder(getBindHostToBuilder().get());
		dockerConfiguration = customizeBuilderAuthentication(dockerConfiguration);
		dockerConfiguration = customizePublishAuthentication(dockerConfiguration);
		return dockerConfiguration;
	}

	private BuilderDockerConfiguration customizeHost(BuilderDockerConfiguration dockerConfiguration) {
		String context = getContext().getOrNull();
		String host = getHost().getOrNull();
		if (context != null && host != null) {
			throw new GradleException(
					"Invalid Docker configuration, either context or host can be provided but not both");
		}
		if (context != null) {
			return dockerConfiguration.withContext(context);
		}
		if (host != null) {
			return dockerConfiguration.withHost(host, getTlsVerify().get(), getCertPath().getOrNull());
		}
		return dockerConfiguration;
	}

	private BuilderDockerConfiguration customizeBuilderAuthentication(BuilderDockerConfiguration dockerConfiguration) {
		return dockerConfiguration.withBuilderRegistryAuthentication(getRegistryAuthentication("builder",
				this.builderRegistry, DockerRegistryAuthentication.configuration(null)));
	}

	private BuilderDockerConfiguration customizePublishAuthentication(BuilderDockerConfiguration dockerConfiguration) {
		return dockerConfiguration

View on GitHub (pinned to 270dfe353f)