spring-projects/spring-boot · error · IllegalStateException

Error creating Docker registry authentication header

Error message

Error creating Docker registry authentication header

What it means

JsonEncodedDockerRegistryAuthentication.createAuthHeader serializes the auth object to JSON via SharedJsonMapper, then Base64URL-encodes the bytes to build the X-Registry-Auth header sent to the Docker daemon. A JacksonException means the object graph could not be serialized. With the shipped concrete auth types (only String/scalar fields) this branch is effectively unreachable.

Source

Thrown at buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/configuration/JsonEncodedDockerRegistryAuthentication.java:48

 *
 * @author Scott Frederick
 */
class JsonEncodedDockerRegistryAuthentication implements DockerRegistryAuthentication {

	@JsonIgnore
	private @Nullable String authHeader;

	@Override
	public @Nullable String getAuthHeader() {
		return this.authHeader;
	}

	protected void createAuthHeader() {
		try {
			this.authHeader = Base64.getUrlEncoder().encodeToString(SharedJsonMapper.get().writeValueAsBytes(this));
		}
		catch (JacksonException ex) {
			throw new IllegalStateException("Error creating Docker registry authentication header", ex);
		}
	}

}

View on GitHub (pinned to 270dfe353f)

Solutions

1. Inspect the wrapped JacksonException cause to find the offending property name.
2. Annotate the non-serializable field with @JsonIgnore, or remove it from the auth object.
3. Keep auth POJOs limited to String/scalar fields (username, password, identitytoken, registrytoken).

Example fix

// before: subclass adds a non-serializable field
class MyAuth extends JsonEncodedDockerRegistryAuthentication {
    private KeyStore trustStore; // triggers JacksonException
}
// after: exclude it
class MyAuth extends JsonEncodedDockerRegistryAuthentication {
    @JsonIgnore
    private KeyStore trustStore;
}

try {
    auth.createAuthHeader();
} catch (IllegalStateException ex) {
    if (ex.getCause() instanceof JacksonException) {
        // fall back to an anonymous (empty) X-Registry-Auth header
        authHeader = Base64.getUrlEncoder().encodeToString("{}".getBytes());
    } else throw ex;
}

When it happens

Trigger: createAuthHeader() at line 45 calls SharedJsonMapper.get().writeValueAsBytes(this) and Jackson throws because a field on the object (or a subclass) holds a non-serializable value, a circular reference, or an annotation mismatch.

Common situations: A custom subclass of JsonEncodedDockerRegistryAuthentication adding a non-serializable field (e.g. a KeyStore, InputStream, or lambda) without @JsonIgnore; a Jackson version/mapper mismatch where annotations are not honored.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Error parsing Docker configuration file '{}'
• Error parsing Docker context metadata file '{}'
• Invalid Docker {} registry configuration, either token or us
• Invalid Docker {type} registry configuration, either token o
• Docker API version must be at least %s to support this featu

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