spring-projects/spring-boot · error · IllegalArgumentException

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 Docker.customizeHost as an IllegalArgumentException when both <docker><context> and <docker><host> are configured at the same time. These are two mutually exclusive ways to locate the Docker daemon: host is an explicit daemon URL, context is a named Docker CLI context to derive host/cert config from. Supplying both is ambiguous, so the plugin refuses to guess.

Source

Thrown at build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Docker.java:163

	 * 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.
	 * @param log the output log
	 * @param publish whether the image should be published
	 * @return the Docker configuration
	 */
	BuilderDockerConfiguration asDockerConfiguration(Log log, boolean publish) {
		BuilderDockerConfiguration dockerConfiguration = new BuilderDockerConfiguration();
		dockerConfiguration = customizeHost(dockerConfiguration);
		dockerConfiguration = dockerConfiguration.withBindHostToBuilder(this.bindHostToBuilder);
		dockerConfiguration = customizeBuilderAuthentication(log, dockerConfiguration);
		dockerConfiguration = customizePublishAuthentication(log, dockerConfiguration, publish);
		return dockerConfiguration;
	}

	private BuilderDockerConfiguration customizeHost(BuilderDockerConfiguration dockerConfiguration) {
		if (this.context != null && this.host != null) {
			throw new IllegalArgumentException(
					"Invalid Docker configuration, either context or host can be provided but not both");
		}
		if (this.context != null) {
			return dockerConfiguration.withContext(this.context);
		}
		if (this.host != null) {
			return dockerConfiguration.withHost(this.host, this.tlsVerify, this.certPath);
		}
		return dockerConfiguration;
	}

	private BuilderDockerConfiguration customizeBuilderAuthentication(Log log,
			BuilderDockerConfiguration dockerConfiguration) {
		DockerRegistryAuthentication authentication = DockerRegistryAuthentication.configuration(null,
				(message, ex) -> log.warn(message));
		return dockerConfiguration.withBuilderRegistryAuthentication(
				getRegistryAuthentication("builder", this.builderRegistry, authentication));
	}

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Decide on one strategy — keep either <host> or <context>, remove the other.
2. If targeting a remote daemon explicitly, use <host> and drop <context>.
3. If relying on Docker CLI contexts (e.g. colima, podman), use <context> and drop <host>.
4. Audit parent and child POMs for inherited docker configuration that combine the two.

Example fix

// before
<docker>
  <host>unix:///var/run/docker.sock</host>
  <context>default</context>
</docker>
// after — pick one
<docker>
  <host>unix:///var/run/docker.sock</host>
</docker>

// Reject POMs that set both docker.host and docker.context
boolean conflictingDockerCfg(String host, String context) {
    return host != null && !host.isBlank() && context != null && !context.isBlank();
}

When it happens

Trigger: Configuring <docker><host>unix:///var/run/docker.sock</host> and <docker><context>default</context> simultaneously in the build-image configuration; passing both -Dspring-boot.build-image.docker.host and -Dspring-boot.build-image.docker.context on the command line; inheriting a parent POM that sets one and overriding with the other in a child module.

Common situations: Migrating from host-based to context-based Docker config and forgetting to remove the old host entry; team-shared parent POM sets host while a developer's context-specific override adds context; CI injecting both via environment-derived properties.

Related errors

• A jar or war file is required for building image
• Invalid Docker {} registry configuration, either token or us
• Failed to load layers configuration with name '%s': '%s' not
• Failed to process custom layers configuration {}
• Could not build classpath

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