spring-projects/spring-boot · error · IllegalStateException

Failed to process custom layers configuration {}

Error message

Failed to process custom layers configuration {}

What it means

Thrown by AbstractPackagerMojo.getCustomLayers as an IllegalStateException wrapping any Exception raised while opening, parsing (with secure DocumentBuilderFactory), or interpreting a custom layers configuration. It covers both the <configuration> file path and the <configurationName> classpath forms, and aggregates XML parse errors, IOException from FileInputStream, and downstream CustomLayersProvider failures. The message appends the source identifier (absolute path or classpath location) to help localize the offending file.

Source

Thrown at build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java:227

		return IMPLICIT_LAYERS;
	}

	private InputStream loadLayersConfigurationFromClasspath(String name, String location) {
		InputStream in = this.pluginDescriptor.getClassRealm().getResourceAsStream(location);
		if (in == null) {
			throw new IllegalStateException(
					"Failed to load layers configuration with name '%s': '%s' not found".formatted(name, location));
		}
		return in;
	}

	private CustomLayers getCustomLayers(String source, InputStreamSource inputStreamSource) {
		try {
			Document document = getDocumentIfAvailable(inputStreamSource);
			return new CustomLayersProvider().getLayers(document);
		}
		catch (Exception ex) {
			throw new IllegalStateException("Failed to process custom layers configuration " + source, ex);
		}
	}

	private Document getDocumentIfAvailable(InputStreamSource source) throws Exception {
		try (InputStream in = source.getInputStream()) {
			InputSource inputSource = new InputSource(in);
			DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
			factory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
			factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
			factory.setNamespaceAware(true);
			DocumentBuilder builder = factory.newDocumentBuilder();
			return builder.parse(inputSource);
		}
	}

	/**
	 * Return {@link Libraries} that the packager can use.
	 * @param unpacks any libraries that require unpack

View on GitHub (pinned to 5b2dbdbb8b)

Solutions

  1. Open the referenced layers.xml and validate it is well-formed XML (e.g. xmllint --noout layers.xml).
  2. Validate against the Spring Boot layers.xsd for your version (see CustomLayersProvider / spring-boot-loader-tools).
  3. Check the wrapped cause in the stack trace — it will indicate whether this is a parse error, an XSD validation failure, or an IOException.
  4. Ensure the path in <configuration> is absolute or correctly relative to the project basedir and that the build user can read it.

Example fix

// before — layers.xml had a typo in a closing tag
<layerOrder><layer>dependencies</layer><layer>application</layr></layerOrder>
// after
<layerOrder><layer>dependencies</layer><layer>application</layer></layerOrder>
Defensive patterns

Strategy: validation

Validate before calling

// Validate the layers.xml file is well-formed before invoking repackage
import javax.xml.parsers.DocumentBuilderFactory;
import java.io.File;

void ensureWellFormed(File layersXml) throws Exception {
    var f = DocumentBuilderFactory.newInstance();
    f.setFeature(javax.xml.XMLConstants.FEATURE_SECURE_PROCESSING, true);
    f.newDocumentBuilder().parse(layersXml); // throws on malformed XML
}

Try / catch

// In a custom Mojo wrapper or integration test
try {
    // invoke repackage / build-image that uses custom layers
} catch (IllegalStateException ex) {
    if (ex.getMessage().contains("Failed to process custom layers configuration")) {
        // log the source path from the message, fail the build with a clear hint
    }
    throw ex;
}

Prevention

When it happens

Trigger: Pointing <layers><configuration> at a file that is malformed XML, references an unknown DOCTYPE, or is not readable; a classpath layers.xml that fails XSD validation in CustomLayersProvider.getLayers; an I/O error reading the configured file (permissions, missing file mid-build).

Common situations: Hand-editing layers.xml and introducing a syntax error; copying a layers.xml from an older Spring Boot version that uses elements no longer allowed by the bundled XSD; file permissions changed between build steps; CI checking out files with CRLF line endings that confuse the parser (rare).

Related errors

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