spring-projects/spring-boot · critical · IllegalStateException

Unable to load layers XSD

Error message

Unable to load layers XSD

What it means

IllegalStateException thrown by CustomLayersProvider.loadSchema when SchemaFactory cannot load the bundled layers.xsd resource as a W3C Schema. The XSD ships inside the plugin's own JAR; failure to construct a Schema from it indicates a classpath/JAR integrity problem rather than a user configuration problem.

Solutions

1. Force re-download: `mvn dependency:purge-local-repository -DreResolve=true` or delete ~/.m2/repository/org/springframework/boot/spring-boot-maven-plugin and re-resolve.
2. Pin a single, known-good spring-boot-maven-plugin version in <pluginManagement> to avoid shadowing.
3. Verify the plugin JAR integrity (`jar tf` should list org/springframework/boot/maven/layers.xsd).
4. If the error persists, file a Spring Boot issue — the bundled XSD should always load.

// CI pre-flight: assert the plugin JAR carries the bundled XSD:
//   jar tf ~/.m2/repository/org/springframework/boot/spring-boot-maven-plugin/<ver>/spring-boot-maven-plugin-<ver>.jar \
//     | grep -q org/springframework/boot/maven/layers.xsd
// If absent, purge and re-resolve.

try {
    // invoke goal that loads layers XSD
} catch (IllegalStateException ex) {
    if ("Unable to load layers XSD".equals(ex.getMessage())) {
        // purge ~/.m2/.../spring-boot-maven-plugin and re-resolve, then retry
    }
    throw ex;
}

When it happens

Trigger: getClass().getResource("layers.xsd") returns a URL the SchemaFactory cannot parse (SAXException during newSchema). This is essentially never a user-input issue — the resource itself is missing, corrupted, or shadowed by an incompatible copy.

Common situations: Plugin JAR corrupted in local .m2 cache; an old/incompatible spring-boot-maven-plugin version on the classpath shadowing the resolved one; partial download of the plugin artifact; custom classloader tricks stripping resources.

Related errors

• Failed to load layers configuration with name
• Invalid layers.xml configuration
• Could not build classpath
• Failed to process custom layers configuration
• Multiple ' ' nodes found

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

Appendix: source

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

	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) {
		return getSelectors(root, "dependencies", (element) -> getLibrarySelector(element, LibraryContentFilter::new));
	}

	private List<Layer> getLayers(Element root) {
		Element layerOrder = getChildElement(root, "layerOrder");
		if (layerOrder == null) {
			return Collections.emptyList();
		}
		return getChildNodeTextContent(layerOrder, "layer").stream().map(Layer::new).toList();
	}

View on GitHub (pinned to 270dfe353f)