spring-projects/spring-boot · error · IllegalStateException

Failed to process custom layers configuration {source}

Error message

Failed to process custom layers configuration {source}

What it means

Wrapped IllegalStateException thrown by AbstractPackagerMojo.getCustomLayers when any Exception occurs while turning the layers XML into a CustomLayers object. The pipeline is: open the InputStream, build a secure DocumentBuilderFactory, parse, then hand the Document to CustomLayersProvider.getLayers. Anything from XML parsing errors, XSD validation failures, malformed content, or programmatic CustomLayers construction failures lands here.

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 270dfe353f)

Solutions

  1. Read the wrapped cause (ex) in the stack trace — it carries the precise XML/SAX or runtime error to fix.
  2. Validate your layers.xml against the bundled layers.xsd (see CustomLayersProvider.loadSchema) using any XSD validator.
  3. Align the layers.xml format with the Spring Boot version of the plugin you are running.
  4. Remove the <configurationName> temporarily to confirm the build succeeds with IMPLICIT_LAYERS, isolating the problem to your custom file.

Example fix

// before: <layers><application><into><include>**/*</include></into></application></layers>  <!-- malformed -->
// after:  <layers><application><into layer="dependencies"><include>**/*</include></into></application></layers>
Defensive patterns

Strategy: validation

Validate before calling

// Validate layers.xml against the bundled XSD before invoking the plugin goal:
SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema schema = sf.newSchema(getClass().getResource("/org/springframework/boot/maven/layers.xsd"));
Validator v = schema.newValidator();
v.setErrorHandler(new CollectingErrorHandler()); // collect all errors
v.validate(new StreamSource(layersXmlFile));
// fail fast if any errors collected

Try / catch

try {
    // invoke goal that triggers getCustomLayers
} catch (IllegalStateException ex) {
    if (ex.getMessage().startsWith("Failed to process custom layers configuration")) {
        Throwable cause = ex.getCause(); // SAX/IO/runtime detail
    }
    throw ex;
}

Prevention

When it happens

Trigger: A layers.xml that is malformed XML, references unknown elements, fails XSD validation, or triggers an exception inside CustomLayersProvider.getLayers/CustomLayers construction. The catch is broad (catch Exception) and wraps the cause.

Common situations: Hand-authored layers.xml with typos or wrong element names; an older layers.xml format used against a newer plugin that tightened the schema; encoding issues in the XML; an accidental <application>/<dependencies> selector referencing an invalid filter shape.

Related errors

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