spring-projects/spring-boot · error · IllegalStateException

Invalid layers.xml configuration

Error message

Invalid layers.xml configuration

What it means

Thrown by CustomLayersProvider.validate as an IllegalStateException when the parsed layers.xml document fails XSD validation (SAXException) or cannot be read by the Validator (IOException). The document was already parsed as XML (so it is well-formed); this error means it violates the schema defined by layers.xsd — wrong element names, unexpected child structure, invalid attribute values, etc.

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 5b2dbdbb8b)

Solutions

1. Open layers.xsd bundled with your Spring Boot version (org/springframework/boot/maven/layers.xsd) and align your layers.xml to it.
2. Read the wrapped SAXException — it names the failing element/attribute and the XSD rule.
3. Replace the custom layers.xml with a minimal valid one and re-add complexity incrementally.
4. Consult the Spring Boot reference for layers configuration matching your version.

Example fix

// before — element not allowed by XSD
<application>
  <selection layer="deps"><include>**/*.class</include></selection>
</application>
// after — schema-correct element names
<application>
  <into layer="deps"><include>**/*.class</include></into>
</application>

// Validate layers.xml against the bundled XSD at build time
import javax.xml.validation.SchemaFactory, Validator, Schema;
import javax.xml.XMLConstants;
import javax.xml.transform.stream.StreamSource;
import java.io.File;

void validate(File layersXml, File layersXsd) throws Exception {
    SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
    Schema s = sf.newSchema(layersXsd);
    s.newValidator().validate(new StreamSource(layersXml));
}

When it happens

Trigger: A layers.xml that is well-formed XML but uses elements or attributes not allowed by the Spring Boot layers XSD for the plugin version in use; an <include>/<exclude> with content that the schema restricts; a <layerOrder> with an empty <layer/> when the schema requires text content; migrating a layers.xml across Spring Boot major versions where the XSD changed.

Common situations: Copying a layers.xml sample from an older Spring Boot doc into a newer plugin; hand-authoring layers.xml without consulting the XSD; adding custom elements that the schema does not permit.

Related errors

• Multiple '{}' nodes found
• Failed to process custom layers configuration {}
• Unable to load layers XSD
• Failed to load layers configuration with name '%s': '%s' not
• Could not build classpath

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