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() during asDockerConfiguration() when both docker.context and docker.host are set. Docker can be targeted either by a context name or by an explicit host URL, but not both; setting both is ambiguous and rejected as GradleException at line 136.

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 5b2dbdbb8b)

Solutions

1. Choose one: set either docker { context = 'my-context' } or docker { host = 'tcp://docker:2375' }, not both.
2. Remove conflicting entries from gradle.properties, environment, and the build script.
3. If using Docker contexts exclusively, leave host unset (and vice versa).
4. Run ./gradlew properties | grep -i docker to see effective values.

Example fix

// before: both set
bootBuildImage {
    docker {
        context = 'desktop-linux'
        host = 'tcp://docker.example.com:2375'
    }
}
// after: pick one
bootBuildImage {
    docker {
        host = 'tcp://docker.example.com:2375'
        tlsVerify = true
    }
}

// Validate that context and host are not both set before running bootBuildImage
val ctx = (tasks.named("bootBuildImage").get() as org.springframework.boot.gradle.tasks.bundling.BootBuildImage)
    .docker.context.orNull
val host = (tasks.named("bootBuildImage").get() as org.springframework.boot.gradle.tasks.bundling.BootBuildImage)
    .docker.host.orNull
check(ctx == null || host == null) {
    "Set either docker.context or docker.host, not both"
}

When it happens

Trigger: bootBuildImage runs createRequest() -> asDockerConfiguration() -> customizeHost(); getContext().getOrNull() and getHost().getOrNull() are both non-null, triggering the throw.

Common situations: CI sets docker.host while the developer's build also sets docker.context; copy-pasting both from docs; switching from context-based to host-based config without removing the other; environment overlay (gradle.properties) supplying one and the build script the other.

Related errors

• Each image building cache can be configured only once
• Invalid Docker {} registry configuration, either token or us
• Each image building cache can be configured only once
• Invalid value for option '--environment'. Expected 'NAME=VAL
• Main class name has not been configured and it could not be

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