spring-projects/spring-boot · error · GradleException

Invalid Docker registry configuration, either token or…

Error message

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

What it means

Thrown by DockerSpec.getRegistryAuthentication when a DockerRegistrySpec is provided (non-null, non-empty-auth) but has neither token-only auth (hasTokenAuth false) nor user/password auth (hasUserAuth false). The method first checks for token auth, then user auth; if neither is fully present, it throws. The 'type' placeholder in the message identifies which registry (e.g. builder or publish).

Solutions

Provide a complete token auth (token set) OR complete user auth (username AND password set) — not both incomplete.
Check that username and password are both non-null when using user/password auth.
If using token auth, ensure only the token is set.
Verify credentials sourced from gradle.properties or environment variables are actually resolving (no typos in property names).

Example fix

// before
tasks.bootBuildImage {
    docker {
        publishRegistry {
            username = "myuser"
            // password missing -> throws
        }
    }
}
// after
tasks.bootBuildImage {
    docker {
        publishRegistry {
            username = "myuser"
            password = "secret"
        }
    }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate registry auth completeness before the task runs.
DockerRegistrySpec reg = dockerSpec.getPublishRegistry();
if (reg != null && !reg.hasEmptyAuth()) {
    boolean tokenOk = reg.hasTokenAuth();
    boolean userOk = reg.hasUserAuth();
    if (!tokenOk && !userOk) {
        throw new GradleException("Provide either token or username+password for the registry.");
    }
}

Prevention

Provide complete credentials: token alone, or username AND password together.
Verify gradle.properties / environment variables resolve before the build.
Avoid mixing token and username/password auth in the same registry spec.

When it happens

Trigger: Configuring docker.builderRegistry or docker.publishRegistry with a partial credentials object: e.g. username set but no password, or password set but no username, and no token either. Also triggered if the registry spec has some fields but neither auth path is complete.

Common situations: Setting username but forgetting password (or vice versa) in publishRegistry or builderRegistry. Providing a username/password in one place and a token in another, then removing one partially. Secrets managed via environment/gradle.properties that are not resolved, leaving the spec half-populated.

Related errors

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

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