spring-projects/spring-boot · error · GradleException

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 DockerSpec.getRegistryAuthentication() when a builder or publish registry has some auth fields set but neither a complete username/password pair (both username AND password) nor a token alone. The type ('builder' or 'publish') is interpolated into the message. It is a GradleException raised during asDockerConfiguration().

Source

Thrown at build-plugin/spring-boot-gradle-plugin/src/main/java/org/springframework/boot/gradle/tasks/bundling/DockerSpec.java:171

	private BuilderDockerConfiguration customizePublishAuthentication(BuilderDockerConfiguration dockerConfiguration) {
		return dockerConfiguration
			.withPublishRegistryAuthentication(getRegistryAuthentication("publish", this.publishRegistry,
					DockerRegistryAuthentication.configuration(DockerRegistryAuthentication.EMPTY_USER)));
	}

	private DockerRegistryAuthentication getRegistryAuthentication(String type, @Nullable DockerRegistrySpec registry,
			DockerRegistryAuthentication fallback) {
		if (registry == null || registry.hasEmptyAuth()) {
			return fallback;
		}
		if (registry.hasTokenAuth() && !registry.hasUserAuth()) {
			return DockerRegistryAuthentication.token(registry.getToken().get());
		}
		if (registry.hasUserAuth() && !registry.hasTokenAuth()) {
			return DockerRegistryAuthentication.user(registry.getUsername().get(), registry.getPassword().get(),
					registry.getUrl().getOrNull(), registry.getEmail().getOrNull());
		}
		throw new GradleException("Invalid Docker " + type
				+ " registry configuration, either token or username/password must be provided");
	}

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

		/**
		 * Returns the username to use when authenticating to the Docker registry.
		 * @return the registry username
		 */
		@Input
		@Optional
		public abstract Property<String> getUsername();

		/**
		 * Returns the password to use when authenticating to the Docker registry.

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. For user auth, always set both username and password: builderRegistry { username='...'; password='...' }.
2. For token auth, set only token and nothing else: builderRegistry { token='...' }.
3. Remove any partial credentials (e.g., a stray url or email) when using token auth.
4. Inject credentials from environment/secret managers so both fields are populated atomically.

Example fix

// before: username only -> throws
bootBuildImage {
    docker {
        publishRegistry {
            username = System.getenv('REG_USER')
            // password missing
        }
    }
}
// after: complete credentials
bootBuildImage {
    docker {
        publishRegistry {
            username = System.getenv('REG_USER')
            password = System.getenv('REG_PASS')
            url = 'https://registry.example.com'
        }
    }
}

fun validateRegistry(user: String?, pass: String?, token: String?) {
    val hasUser = !user.isNullOrBlank() && !pass.isNullOrBlank()
    val hasToken = !token.isNullOrBlank()
    check(hasUser xor hasToken) {
        "Provide either token, or username+password (not both, not partial)"
    }
}

When it happens

Trigger: builderRegistry/publishRegistry has hasEmptyAuth()==false and (hasTokenAuth()==hasUserAuth() (both true: token mixed with partial creds) or both false: e.g. username without password, or only url/email set) — line 171 throws.

Common situations: Setting username but forgetting password (or vice versa); providing a token and also a username; setting only url/email; credentials supplied via environment that partially populated the properties.

Related errors

• Invalid Docker configuration, either context or host can be
• Invalid value for option '--environment'. Expected 'NAME=VAL
• Each image building cache can be configured only once
• Each image building cache can be configured only once
• Invalid Docker {} registry configuration, either token or us

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