{"record":{"id":"d40ff53c9fbd8c89","repo":"quarkusio/quarkus","slug":"failed-to-parse-webfragment-location","errorCode":null,"errorMessage":"Failed to parse ${webFragment} ${location}","messagePattern":"Failed to parse (.+?) (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/undertow/deployment/src/main/java/io/quarkus/undertow/deployment/WebXmlParsingBuildStep.java","lineNumber":136,"sourceCode":"     */\n    private List<WebFragmentMetaData> parseWebFragments(ApplicationArchivesBuildItem applicationArchivesBuildItem) {\n        List<WebFragmentMetaData> webFragments = new ArrayList<>();\n        for (ApplicationArchive archive : applicationArchivesBuildItem.getAllArchives()) {\n            archive.accept(tree -> {\n                Path webFragment = tree.getPath(WEB_FRAGMENT_XML);\n                if (webFragment != null && Files.isRegularFile(webFragment)) {\n                    try (InputStream is = Files.newInputStream(webFragment)) {\n                        final XMLInputFactory inputFactory = XMLInputFactory.newInstance();\n                        inputFactory.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);\n                        inputFactory.setXMLResolver(NoopXMLResolver.create());\n                        XMLStreamReader xmlReader = inputFactory.createXMLStreamReader(is);\n\n                        WebFragmentMetaData webFragmentMetaData = WebFragmentMetaDataParser.parse(xmlReader,\n                                PropertyReplacers.resolvingExpressionReplacer(new MPConfigExpressionResolver()));\n                        webFragments.add(webFragmentMetaData);\n\n                    } catch (XMLStreamException e) {\n                        throw new RuntimeException(\"Failed to parse \" + webFragment + \" \" + e.getLocation(), e);\n                    } catch (IOException e) {\n                        throw new RuntimeException(\"Failed to parse \" + webFragment, e);\n                    }\n                }\n            });\n        }\n        return webFragments;\n    }\n\n}\n","sourceCodeStart":118,"sourceCodeEnd":147,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/undertow/deployment/src/main/java/io/quarkus/undertow/deployment/WebXmlParsingBuildStep.java#L118-L147","documentation":"During Undertow deployment, Quarkus parses web-fragment.xml files discovered in WEB-INF/lib JARs; XMLStreamException during parsing is wrapped in a RuntimeException that includes the file location and the XML parser location. Deployment fails fast so malformed descriptors are fixed rather than silently ignored.","triggerScenarios":"parseWebFragments (called from webFragments build step) encounters a web-fragment.xml that is not well-formed XML or violates the descriptor schema while WebFragmentMetaDataParser.parse reads it.","commonSituations":"Dependency JAR contains hand-edited/broken web-fragment.xml; XML declares encoding that does not match actual bytes; unescaped characters (<, &) in the descriptor; schema version mismatch with validation enabled.","solutions":["Identify the offending JAR from the path in the message and inspect its META-INF/web-fragment.xml","Validate the XML: xmllint --noout web-fragment.xml, then fix well-formedness/schema errors","Upgrade or exclude the faulty dependency (exclude the JAR or replace it with a fixed version)","Check for encoding mismatch between the XML declaration and the file's actual encoding"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// validate web-fragment.xml in dependency JARs before deployment\ntry (InputStream in = jar.getInputStream(jar.getEntry(\"META-INF/web-fragment.xml\"))) {\n    DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(in); // throws on malformed XML\n}","typeGuard":null,"tryCatchPattern":"try {\n    // build with undertow deployment\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to parse\")) {\n        log.errorf(e.getCause(), \"Malformed descriptor: %s\", e.getMessage());\n        // fix or exclude the offending dependency JAR\n    }\n}","preventionTips":["Run xmllint on web-fragment.xml files shipped in your own libraries","Pin and upgrade dependencies known to ship broken descriptors","Exclude faulty JARs from WEB-INF/lib when their descriptors are not needed","Check XML declaration vs actual file encoding when descriptors are edited"],"tags":["undertow","web-fragment","xml","deployment"],"backgroundTag":"xml-parse-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}