{"id":"67f08923efb928ad","repo":"spring-projects/spring-boot","slug":"failed-to-process-custom-layers-configuration","errorCode":null,"errorMessage":"Failed to process custom layers configuration {}","messagePattern":"Failed to process custom layers configuration (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java","lineNumber":227,"sourceCode":"\t\treturn IMPLICIT_LAYERS;\n\t}\n\n\tprivate InputStream loadLayersConfigurationFromClasspath(String name, String location) {\n\t\tInputStream in = this.pluginDescriptor.getClassRealm().getResourceAsStream(location);\n\t\tif (in == null) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\"Failed to load layers configuration with name '%s': '%s' not found\".formatted(name, location));\n\t\t}\n\t\treturn in;\n\t}\n\n\tprivate CustomLayers getCustomLayers(String source, InputStreamSource inputStreamSource) {\n\t\ttry {\n\t\t\tDocument document = getDocumentIfAvailable(inputStreamSource);\n\t\t\treturn new CustomLayersProvider().getLayers(document);\n\t\t}\n\t\tcatch (Exception ex) {\n\t\t\tthrow new IllegalStateException(\"Failed to process custom layers configuration \" + source, ex);\n\t\t}\n\t}\n\n\tprivate Document getDocumentIfAvailable(InputStreamSource source) throws Exception {\n\t\ttry (InputStream in = source.getInputStream()) {\n\t\t\tInputSource inputSource = new InputSource(in);\n\t\t\tDocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();\n\t\t\tfactory.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);\n\t\t\tfactory.setFeature(\"http://apache.org/xml/features/disallow-doctype-decl\", true);\n\t\t\tfactory.setNamespaceAware(true);\n\t\t\tDocumentBuilder builder = factory.newDocumentBuilder();\n\t\t\treturn builder.parse(inputSource);\n\t\t}\n\t}\n\n\t/**\n\t * Return {@link Libraries} that the packager can use.\n\t * @param unpacks any libraries that require unpack","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/spring-projects/spring-boot/blob/5b2dbdbb8be64415eb6552f81ff7c449c8d251e6/build-plugin/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java#L209-L245","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Open the referenced layers.xml and validate it is well-formed XML (e.g. xmllint --noout layers.xml).","Validate against the Spring Boot layers.xsd for your version (see CustomLayersProvider / spring-boot-loader-tools).","Check the wrapped cause in the stack trace — it will indicate whether this is a parse error, an XSD validation failure, or an IOException.","Ensure the path in <configuration> is absolute or correctly relative to the project basedir and that the build user can read it."],"exampleFix":"// before — layers.xml had a typo in a closing tag\n<layerOrder><layer>dependencies</layer><layer>application</layr></layerOrder>\n// after\n<layerOrder><layer>dependencies</layer><layer>application</layer></layerOrder>","handlingStrategy":"validation","validationCode":"// Validate the layers.xml file is well-formed before invoking repackage\nimport javax.xml.parsers.DocumentBuilderFactory;\nimport java.io.File;\n\nvoid ensureWellFormed(File layersXml) throws Exception {\n    var f = DocumentBuilderFactory.newInstance();\n    f.setFeature(javax.xml.XMLConstants.FEATURE_SECURE_PROCESSING, true);\n    f.newDocumentBuilder().parse(layersXml); // throws on malformed XML\n}","typeGuard":null,"tryCatchPattern":"// In a custom Mojo wrapper or integration test\ntry {\n    // invoke repackage / build-image that uses custom layers\n} catch (IllegalStateException ex) {\n    if (ex.getMessage().contains(\"Failed to process custom layers configuration\")) {\n        // log the source path from the message, fail the build with a clear hint\n    }\n    throw ex;\n}","preventionTips":["Add a build-time check (xmllint or a small Java test) that parses your layers.xml.","Keep layers.xml under version control and review changes against the bundled layers.xsd.","Pin the Spring Boot plugin version so the XSD contract does not change unexpectedly."],"tags":["maven","layers","xml","configuration","spring-boot"],"analyzedSha":"5b2dbdbb8be64415eb6552f81ff7c449c8d251e6","analyzedAt":"2026-08-04T18:53:14.967Z","schemaVersion":2}