What causes "Failed to parse ${webFragment} ${location}" in quarkusio/quarkus?

Identify the offending JAR from the path in the message and inspect its META-INF/web-fragment.xml

quarkusio/quarkus · error · RuntimeException

Failed to parse ${webFragment} ${location}

Error message

Failed to parse ${webFragment} ${location}

What it means

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.

Source

Thrown at extensions/undertow/deployment/src/main/java/io/quarkus/undertow/deployment/WebXmlParsingBuildStep.java:136

     */
    private List<WebFragmentMetaData> parseWebFragments(ApplicationArchivesBuildItem applicationArchivesBuildItem) {
        List<WebFragmentMetaData> webFragments = new ArrayList<>();
        for (ApplicationArchive archive : applicationArchivesBuildItem.getAllArchives()) {
            archive.accept(tree -> {
                Path webFragment = tree.getPath(WEB_FRAGMENT_XML);
                if (webFragment != null && Files.isRegularFile(webFragment)) {
                    try (InputStream is = Files.newInputStream(webFragment)) {
                        final XMLInputFactory inputFactory = XMLInputFactory.newInstance();
                        inputFactory.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);
                        inputFactory.setXMLResolver(NoopXMLResolver.create());
                        XMLStreamReader xmlReader = inputFactory.createXMLStreamReader(is);

                        WebFragmentMetaData webFragmentMetaData = WebFragmentMetaDataParser.parse(xmlReader,
                                PropertyReplacers.resolvingExpressionReplacer(new MPConfigExpressionResolver()));
                        webFragments.add(webFragmentMetaData);

                    } catch (XMLStreamException e) {
                        throw new RuntimeException("Failed to parse " + webFragment + " " + e.getLocation(), e);
                    } catch (IOException e) {
                        throw new RuntimeException("Failed to parse " + webFragment, e);
                    }
                }
            });
        }
        return webFragments;
    }

}

View on GitHub (pinned to e1c734241f)

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

Defensive patterns

Strategy: try-catch

Validate before calling

// validate web-fragment.xml in dependency JARs before deployment
try (InputStream in = jar.getInputStream(jar.getEntry("META-INF/web-fragment.xml"))) {
    DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(in); // throws on malformed XML
}

Try / catch

try {
    // build with undertow deployment
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to parse")) {
        log.errorf(e.getCause(), "Malformed descriptor: %s", e.getMessage());
        // fix or exclude the offending dependency JAR
    }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/d40ff53c9fbd8c89. Report an issue: GitHub.