spring-projects/spring-boot · error · IllegalStateException

Error parsing Docker configuration file '{}'

Error message

Error parsing Docker configuration file '{}'

What it means

Thrown by DockerConfigurationMetadata when reading ~/.docker/config.json (or $DOCKER_CONFIG/config.json). The file's existence is checked first, so this fires only when the file is present but its contents are not valid JSON. DockerConfig.fromJson calls SharedJsonMapper.get().readTree(json); the resulting JacksonException is wrapped in an IllegalStateException naming the offending path. The buildpack reads this file at the start of every Docker-driven build to discover registry auth, credential helpers, and the active Docker context.

Source

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

		DockerConfig dockerConfig = createDockerConfig(configLocation);
		DockerContext dockerContext = createDockerContext(configLocation, dockerConfig.getCurrentContext());
		return new DockerConfigurationMetadata(configLocation, dockerConfig, dockerContext);
	}

	private static String getUserHomeConfigLocation() {
		return Path.of(System.getProperty("user.home"), CONFIG_DIR).toString();
	}

	private static DockerConfig createDockerConfig(String configLocation) {
		Path path = Path.of(configLocation, CONFIG_FILE_NAME);
		if (!path.toFile().exists()) {
			return DockerConfig.empty();
		}
		try {
			return DockerConfig.fromJson(readPathContent(path));
		}
		catch (JacksonException ex) {
			throw new IllegalStateException("Error parsing Docker configuration file '" + path + "'", ex);
		}
	}

	private static DockerContext createDockerContext(String configLocation, @Nullable String currentContext) {
		if (currentContext == null || DEFAULT_CONTEXT.equals(currentContext)) {
			return DockerContext.empty();
		}
		String hash = asHash(currentContext);
		Path metaPath = Path.of(configLocation, CONTEXTS_DIR, META_DIR, hash, CONTEXT_FILE_NAME);
		Path tlsPath = Path.of(configLocation, CONTEXTS_DIR, TLS_DIR, hash, DOCKER_ENDPOINT);
		if (!metaPath.toFile().exists()) {
			throw new IllegalArgumentException("Docker context '" + currentContext + "' does not exist");
		}
		try {
			DockerContext context = DockerContext.fromJson(readPathContent(metaPath));
			if (tlsPath.toFile().isDirectory()) {
				return context.withTlsPath(tlsPath.toString());
			}

View on GitHub (pinned to 270dfe353f)

Solutions

1. Validate the file: run `jq ~/.docker/config.json` or `python -m json.tool ~/.docker/config.json` to find the syntax error.
2. Regenerate the file with `docker logout && docker login`.
3. If unrecoverable, back it up and delete it so DockerConfigurationMetadata falls back to DockerConfig.empty() (path.toFile().exists() == false at line 117).

Example fix

// before (broken JSON, trailing comma)
{ "auths": { "https://index.docker.io": { "auth": "..." }}, }
// after (valid JSON)
{ "auths": { "https://index.docker.io": { "auth": "..." } } }

// Pre-validate config.json before invoking the build
Path cfg = Path.of(
    System.getenvOrDefault("DOCKER_CONFIG",
        Path.of(System.getProperty("user.home"), ".docker").toString()),
    "config.json");
if (Files.exists(cfg)) {
    try {
        SharedJsonMapper.get().readTree(Files.readString(cfg));
    } catch (Exception e) {
        throw new IllegalStateException(
            "~/.docker/config.json is invalid JSON: " + e.getMessage(), e);
    }
}

// Around the build invocation
try {
    build.run();
} catch (IllegalStateException ex) {
    if (ex.getCause() instanceof JacksonException je
            && ex.getMessage().startsWith("Error parsing Docker configuration file")) {
        // surface a user-facing hint pointing at the file in the message
        throw new IllegalStateException(
            "Docker config.json is corrupt. Run `docker login` to regenerate it.", ex);
    }
    throw ex;
}

When it happens

Trigger: DockerConfigurationMetadata.from(environment) resolves a non-null config location, config.json exists, but DockerConfig.fromJson(readPathContent(path)) throws a JacksonException (stray comma, trailing data, BOM, truncated tail, hand-edited syntax error). Caught at line 123 and rethrown.

Common situations: Hand-editing ~/.docker/config.json and leaving a syntax error; a crashed docker login leaving a half-written file; a CI template (Jinja/mustache) leaving an unfilled placeholder; a UTF-8 BOM written by a Windows editor.

Related errors

• Error parsing Docker context metadata file '{}'
• Docker context '{}' does not exist
• Error reading Docker configuration file '{}'
• Error creating Docker registry authentication header
• Invalid Docker configuration, either context or host can be

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