spring-projects/spring-boot · error · IllegalStateException

Failed to read configuration metadata

Error message

Failed to read configuration metadata

What it means

Wrapped inside ConfigurationMetadataRepositoryJsonBuilder.add: when reading a JSON metadata stream, any non-IOException exception (i.e. a parsing/JSON format error from JsonReader) is rethrown as an IllegalStateException with this message and the original exception as cause. IOExceptions are rethrown unchanged; only format/structural problems get this wrapper.

Source

Thrown at configuration-metadata/spring-boot-configuration-metadata/src/main/java/org/springframework/boot/configurationmetadata/ConfigurationMetadataRepositoryJsonBuilder.java:103

	 */
	public ConfigurationMetadataRepository build() {
		SimpleConfigurationMetadataRepository result = new SimpleConfigurationMetadataRepository();
		for (SimpleConfigurationMetadataRepository repository : this.repositories) {
			result.include(repository);
		}
		return result;
	}

	private SimpleConfigurationMetadataRepository add(InputStream in, Charset charset) throws IOException {
		try {
			RawConfigurationMetadata metadata = this.reader.read(in, charset);
			return create(metadata);
		}
		catch (IOException ex) {
			throw ex;
		}
		catch (Exception ex) {
			throw new IllegalStateException("Failed to read configuration metadata", ex);
		}
	}

	private SimpleConfigurationMetadataRepository create(RawConfigurationMetadata metadata) {
		SimpleConfigurationMetadataRepository repository = new SimpleConfigurationMetadataRepository();
		repository.add(metadata.getSources());
		for (ConfigurationMetadataItem item : metadata.getItems()) {
			ConfigurationMetadataSource source = metadata.getSource(item);
			repository.add(item, source);
		}
		Map<String, ConfigurationMetadataProperty> allProperties = repository.getAllProperties();
		for (ConfigurationMetadataHint hint : metadata.getHints()) {
			ConfigurationMetadataProperty property = allProperties.get(hint.getId());
			if (property != null) {
				addValueHints(property, hint);
			}
			else {
				String id = hint.resolveId();

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

1. Inspect the cause exception (ex.getCause()) for the exact JSON/location error and fix the offending metadata file.
2. Validate the resource is a well-formed JSON document matching the configuration-metadata schema before feeding it to the builder.
3. Ensure the stream is not intercepted/corrupted (encoding, truncation) - read it fully and confirm Content-Length/charset.

Example fix

// before
builder.withJsonResource(corruptedOrHtmlStream).build();
  -> IllegalStateException: Failed to read configuration metadata (cause: JsonParseException)
// after
String json = new String(stream.readAllBytes(), StandardCharsets.UTF_8);
// validate json is the expected metadata document, then
builder.withJsonResource(new ByteArrayInputStream(json.getBytes(StandardCharsets.UTF_8))).build();

byte[] bytes = in.readAllBytes();
try (JsonParser p = JsonFactory.createParser(bytes)) {
    while (p.nextToken() != null) { /* structural validation */ }
}
builder.withJsonResource(new ByteArrayInputStream(bytes));

boolean looksLikeMetadataJson(byte[] b) {
    String s = new String(b, StandardCharsets.UTF_8).trim();
    return s.startsWith("{") && (s.contains("\"groups\"") || s.contains("\"properties\""));
}

try { builder.withJsonResource(in).build(); }
catch (IllegalStateException ex) {
    if ("Failed to read configuration metadata".equals(ex.getMessage())) {
        Throwable cause = ex.getCause();
        // log cause (e.g. JsonParseException with line/column), fix the file
    } else throw ex;
}

When it happens

Trigger: Passing an InputStream whose content is not valid configuration-metadata JSON - malformed JSON, missing required fields, wrong structure - so JsonReader.read throws a runtime exception (not IOException) during parsing, caught at line 102 and wrapped.

Common situations: A hand-edited or corrupted spring-configuration-metadata.json; a stream that returned an error page or HTML instead of JSON; a metadata file produced by an incompatible plugin version with a different schema; truncation of the stream.

Related errors

• Can't parse '%s' to instant
• 'files' must not be null
• InputStream must not be null.
• Failed to load layers configuration with name '%s': '%s' not
• Failed to process custom layers configuration {}

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