quarkusio/quarkus · error · RuntimeException

Failed to parse ${webFragment}

Error message

Failed to parse ${webFragment}

What it means

Thrown by WebXmlParsingBuildStep while reading a web-fragment.xml during a Quarkus build. The file exists but cannot be parsed as valid XML (XMLStreamException) or opened/read (IOException). Quarkus re-throws it as a RuntimeException naming the offending fragment and XML location.

Source

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

        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

1. Open the fragment path shown in the message and fix/validate its XML syntax
2. Verify the JAR is not corrupt: `unzip -t app.jar` or delete and re-download the dependency from the local repo
3. If the fragment is from a third-party dependency, exclude it (`mvn dependency:exclude`) or pin a fixed version
4. Check the file encoding matches the XML declaration (add explicit encoding to the declaration)

Example fix

// before (malformed web-fragment.xml)
<web-fragment>
  <servlet><servlet-name>A</servlet-name></servlet>
</web-fragment
// after
<web-fragment version="4.0" xmlns="http://xmlns.jcp.org/xml/ns/javaee">
  <servlet><servlet-name>A</servlet-name><servlet-class>com.acme.A</servlet-class></servlet>
</web-fragment>

// validate bundled web-fragment.xml before build
try (InputStream is = new ZipFile(new File("app.jar")).getInputStream(new ZipEntry("META-INF/web-fragment.xml"))) {
    DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(is); // throws if malformed
}

When it happens

Trigger: A dependency JAR's META-INF/web-fragment.xml (or a project's one on the web-fragment path) is malformed, contains invalid XML characters/encoding, or the file is unreadable/truncated inside the JAR.

Common situations: Corrupt JAR in local Maven repo; hand-edited web-fragment.xml with a syntax error; wrong encoding (e.g. UTF-8 BOM issues); a legacy war-style library bundled in a Quarkus build.

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

• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}
• The class (${name}) cannot be created during deployment.
• Use GeneratedServiceProviderBuildItem to register service pr

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