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

IllegalArgumentException thrown by Docker.customizeHost when both <context> and <host> are configured simultaneously. The builder Docker connection can target either a named context or an explicit host, but not both — supplying both is contradictory, so the plugin refuses to guess.

Solutions

Choose one: keep <context> for a Docker context name OR <host> for an explicit daemon URL, and remove the other.
Check that system properties -Ddocker.host / -Ddocker.context aren't both set in MAVEN_OPTS or CI.
If using docker.context, ensure the context exists (`docker context ls`).

Example fix

// before: <docker><host>tcp://docker.local:2376</host><context>default</context></docker>
// after:  <docker><host>tcp://docker.local:2376</host></docker>

Defensive patterns

Strategy: validation

Validate before calling

// Configuration validation before invoking build-image:
if (docker.getContext() != null && docker.getHost() != null) {
    throw new IllegalArgumentException(
        "Configure either docker.context OR docker.host, not both.");
}

Try / catch

try {
    // invoke build-image
} catch (IllegalArgumentException ex) {
    if (ex.getMessage().contains("either context or host")) {
        // drop one of <context>/<host> and retry
    }
    throw ex;
}

Prevention

Standardize on either context-based or host-based Docker config per environment.
Check MAVEN_OPTS / system properties for stray -Ddocker.host and -Ddocker.context.
Document the chosen mode in the project README.

When it happens

Trigger: Setting both <docker><context>...</context> and <docker><host>...</host></host></docker> in the plugin configuration (or via the matching properties) when invoking build-image/push goals.

Common situations: Configuring <host> for a remote Docker daemon and <context> for a desktop Docker at the same time; copy-pasting examples that each set one; mixing docker.host and docker.context system properties with POM entries.

Related errors

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

Appendix: 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 270dfe353f)