spring-projects/spring-boot · error · IllegalArgumentException

Invalid Docker {type} registry configuration, either token o

Error message

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

What it means

IllegalArgumentException thrown by Docker's registry-authentication builder when a DockerRegistry entry provides neither token auth nor username/password auth. The branch logic accepts token-only, user-only, or — implicitly via fallthrough — none; reaching the final throw means the configuration is incomplete for the given registry type (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 270dfe353f)

Solutions

1. Provide either <token>...</token> OR <username>+<password> for each registry entry, not neither.
2. If using env-driven config (DOCKER_AUTH_* / SPRING_BOOT_DOCKER_*), confirm the variables are exported in the build environment.
3. Remove registry entries that are tag aliases (no auth needed) from the auth-requiring builder/publish list.
4. Use a Docker credential helper / ~/.docker/config.json and drop the explicit block entirely.

Example fix

// before: <publishRegistries><registry><username>ciuser</username></registry></publishRegistries>
// after:  <publishRegistries><registry><username>ciuser</username><password>${env.REGISTRY_PASS}</password></registry></publishRegistries>

// Validate each registry entry before invoking build-image/push:
for (Docker.DockerRegistry r : registries) {
    boolean hasToken = r.getToken() != null;
    boolean hasUser  = r.getUsername() != null && r.getPassword() != null;
    if (!hasToken && !hasUser) {
        throw new IllegalArgumentException(
            "Registry " + r.getUrl() + " has neither token nor username/password");
    }
}

try {
    // invoke build-image or push-image
} catch (IllegalArgumentException ex) {
    if (ex.getMessage().contains("registry configuration, either token or username/password")) {
        // add <token> or <username>+<password> to the offending registry
    }
    throw ex;
}

When it happens

Trigger: Declaring <docker><builder> or <docker><publish> registry entries (or tags/publish-registries) where the entry has neither <token> nor a <username>+<password> pair. The `type` placeholder distinguishes builder auth from publish auth.

Common situations: Listing a registry URL or email without credentials; providing username but no password (or vice versa); using a registry entry meant only as a tag alias while trying to publish; misconfigured environment variables for CI registry auth.

Related errors

• Invalid Docker {} registry configuration, either token or us
• Invalid Docker configuration, either context or host can be
• Failed to load layers configuration with name '%s': '%s' not
• Failed to process custom layers configuration {source}
• Could not build classpath

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