spring-projects/spring-boot · error · IllegalStateException

Invalid layers.xml configuration

Error message

Invalid layers.xml configuration

What it means

IllegalStateException thrown by CustomLayersProvider.validate when XSD validation of the layers document fails with a SAXException (schema violation, malformed element) or IOException (unable to read a referenced resource). The bundled layers.xsd defines the legal grammar; this guard fires before any structural interpretation.

Solutions

1. Open the chained SAXException — it gives line/column and the failed constraint.
2. Validate against the bundled layers.xsd shipped with your plugin version using an XML editor or `xmllint --schema`.
3. Correct element/attribute names and required values per the current schema.
4. Use Spring Boot's documented example as a baseline and incrementally add customizations.

Example fix

// before: <into><include>**/*</include></into>   <!-- missing required 'layer' attribute -->
// after:  <into layer="application"><include>**/*</include></into>

// XSD-validate layers.xml in CI before the plugin runs:
Schema s = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)
    .newSchema(new File("layers.xsd"));
Validator v = s.newValidator();
v.validate(new StreamSource(new File("src/main/resources/META-INF/spring/layers/custom.xml")));

try {
    // invoke goal that triggers CustomLayersProvider.validate
} catch (IllegalStateException ex) {
    if ("Invalid layers.xml configuration".equals(ex.getMessage())) {
        Throwable c = ex.getCause(); // SAXParseException with line/column
    }
    throw ex;
}

When it happens

Trigger: A layers.xml that violates the XSD: unknown elements, missing required attributes, wrong nesting, content type mismatch, or any SAX-reported validity error. Also fires on IOException if the validator needs external resolution and I/O fails.

Common situations: Hand-edited layers.xml with element typos; using a feature from a newer Spring Boot against an older plugin (or vice versa) where the schema differs; copy-pasted example with a missing required attribute such as layer= on <into>.

Related errors

• Failed to process custom layers configuration
• Multiple ' ' nodes found
• Unable to load layers XSD
• Failed to load layers configuration with name
• A jar or war file is required for building image

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

Appendix: source

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

class CustomLayersProvider {

	CustomLayers getLayers(Document document) {
		validate(document);
		Element root = document.getDocumentElement();
		List<ContentSelector<String>> applicationSelectors = getApplicationSelectors(root);
		List<ContentSelector<Library>> librarySelectors = getLibrarySelectors(root);
		List<Layer> layers = getLayers(root);
		return new CustomLayers(layers, applicationSelectors, librarySelectors);
	}

	private void validate(Document document) {
		Schema schema = loadSchema();
		try {
			Validator validator = schema.newValidator();
			validator.validate(new DOMSource(document));
		}
		catch (SAXException | IOException ex) {
			throw new IllegalStateException("Invalid layers.xml configuration", ex);
		}
	}

	private Schema loadSchema() {
		try {
			SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
			return factory.newSchema(getClass().getResource("layers.xsd"));
		}
		catch (SAXException ex) {
			throw new IllegalStateException("Unable to load layers XSD");
		}
	}

	private List<ContentSelector<String>> getApplicationSelectors(Element root) {
		return getSelectors(root, "application", (element) -> getSelector(element, ApplicationContentFilter::new));
	}

	private List<ContentSelector<Library>> getLibrarySelectors(Element root) {

View on GitHub (pinned to 270dfe353f)