spring-projects/spring-boot · error · IllegalArgumentException

Invalid Docker {} registry configuration, either token or us

Error message

Invalid Docker {} registry configuration, either token or username/password must be provided

What it means

Thrown by Docker.getRegistryAuthentication as an IllegalArgumentException when a registry (builder or publish) is configured but provides neither pure token auth nor pure username/password auth. The accepted combinations are exactly token-only or username+password-only; supplying both, supplying only a username without a password (or vice-versa), or supplying a token plus a username triggers this. The {} interpolates 'builder' or 'publish'.

Source

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

	private DockerRegistryAuthentication getRegistryAuthentication(String type, @Nullable DockerRegistry registry,
			DockerRegistryAuthentication fallback) {
		if (registry == null || registry.isEmpty()) {
			return fallback;
		}
		if (registry.hasTokenAuth() && !registry.hasUserAuth()) {
			String token = registry.getToken();
			Assert.state(token != null, "'token' must not be null");
			return DockerRegistryAuthentication.token(token);
		}
		if (registry.hasUserAuth() && !registry.hasTokenAuth()) {
			String username = registry.getUsername();
			String password = registry.getPassword();
			Assert.state(username != null, "'username' must not be null");
			Assert.state(password != null, "'password' must not be null");
			return DockerRegistryAuthentication.user(username, password, registry.getUrl(), registry.getEmail());
		}
		throw new IllegalArgumentException("Invalid Docker " + type
				+ " registry configuration, either token or username/password must be provided");
	}

	/**
	 * Encapsulates Docker registry authentication configuration options.
	 */
	public static class DockerRegistry {

		private @Nullable String username;

		private @Nullable String password;

		private @Nullable String url;

		private @Nullable String email;

		private @Nullable String token;

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Use exactly one auth method: <token> alone, or <username>+<password> together.
2. If using publish, ensure <publishRegistry> has complete credentials (or remove it to use the fallback).
3. Audit the POM and any properties files for stale username/password or token fields.
4. If credentials come from ~/.m2/settings.xml or env, verify all required values resolve.

Example fix

// before — partial credentials
<docker>
  <publishRegistry>
    <username>myuser</username>
  </publishRegistry>
</docker>
// after — complete user/pass, or token only
<docker>
  <publishRegistry>
    <username>myuser</username><password>${env.DOCKER_PASS}</password>
  </publishRegistry>
</docker>

// Validate registry auth shape before build-image
import java.util.Objects;

void checkRegistry(String username, String password, String token, String type) {
    boolean hasUser = username != null && password != null;
    boolean hasToken = token != null;
    if (hasUser == hasToken) { // both set, or both unset-but-not-empty-config
        throw new IllegalArgumentException(
            "Invalid Docker " + type + " registry: provide token OR username+password");
    }
}

When it happens

Trigger: Setting <docker><builder><token>... and <docker><builder><username>... at the same time; configuring a registry with <username> but no <password>; configuring publish auth when image.publish is true but providing only partial credentials; migrating from user/pass to token auth and leaving the old fields populated.

Common situations: CI previously used username/password, switched to a registry token, but the old fields remained in the POM; a secrets-management plugin injecting only one of username/password; publish=true (which forces publish auth resolution) while publishRegistry holds partial credentials.

Related errors

• Invalid Docker configuration, either context or host can be
• Invalid Docker {} registry configuration, either token or us
• A jar or war file is required for building image
• Error packaging archive for image
• Failed to load layers configuration with name '%s': '%s' not

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