spring-projects/spring-boot · error · IllegalStateException

Error parsing Docker context metadata file '{}'

Error message

Error parsing Docker context metadata file '{}'

What it means

The named Docker context's meta.json exists (the existence check at line 135 passed) but DockerContext.fromJson(readPathContent(metaPath)) threw a JacksonException. Docker's context metadata file is normally written by `docker context create` and contains Endpoints/docker/Host and Endpoints/docker/SkipTLSVerify fields; anything that corrupts it triggers this wrap into IllegalStateException naming metaPath.

Source

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

	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());
			}
			return context;
		}
		catch (JacksonException ex) {
			throw new IllegalStateException("Error parsing Docker context metadata file '" + metaPath + "'", ex);
		}
	}

	private static String asHash(String currentContext) {
		try {
			MessageDigest digest = MessageDigest.getInstance("SHA-256");
			byte[] hash = digest.digest(currentContext.getBytes(StandardCharsets.UTF_8));
			return HexFormat.of().formatHex(hash);
		}
		catch (NoSuchAlgorithmException ex) {
			throw new IllegalStateException("SHA-256 is not available", ex);
		}
	}

	private static String readPathContent(Path path) {
		try {
			return Files.readString(path);
		}

View on GitHub (pinned to 270dfe353f)

Solutions

1. Validate the file: `jq < ~/.docker/contexts/meta/<hash>/meta.json`.
2. Recreate the context: `docker context rm <name> && docker context create <name> --docker <endpoint>`.
3. Fall back to the default context: `docker context use default`.

// Validate the context's meta.json before invoking the build
Path meta = resolveContextMetaPath(configLocation, currentContext);
if (Files.exists(meta)) {
    try {
        SharedJsonMapper.get().readTree(Files.readString(meta));
    } catch (Exception e) {
        throw new IllegalStateException(
            "Docker context meta.json at " + meta + " is invalid: " + e.getMessage(), e);
    }
}

try {
    metadata.getContext();
} catch (IllegalStateException ex) {
    if (ex.getCause() instanceof JacksonException
            && ex.getMessage().startsWith("Error parsing Docker context metadata file")) {
        // hint: recreate the context with `docker context rm` + `docker context create`
    }
    throw ex;
}

When it happens

Trigger: createDockerContext reaches line 139 (DockerContext.fromJson), the file's bytes are readable but not valid JSON or do not match the expected node structure, and JacksonException is caught at line 145.

Common situations: Hand-editing contexts/meta/<hash>/meta.json; a crashed `docker context create` leaving a truncated file; schema drift from an incompatible Docker CLI version; copying only part of the contexts/ tree.

Related errors

• Error parsing Docker configuration 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/2472f2d6d34001f2. Report an issue: GitHub.