quarkusio/quarkus · error · IllegalStateException

Unable to parse pom file

Error message

Unable to parse pom file: ${pom}

What it means

The annotation processor discovers extension metadata by parsing the module's pom.xml with a DOM document builder. If parsing fails for any reason (malformed XML, file unreadable, IO error), it wraps the exception in this IllegalStateException. Without a parseable pom, the processor cannot derive the ExtensionModule (name, module type, artifact info) needed for config documentation.

Solutions

1. Open the pom.xml reported in the message and validate its XML (e.g. mvn -q validate or an XML linter); fix syntax errors.
2. Restore the pom from version control if it was corrupted: git checkout -- pom.xml.
3. Check file permissions/readability of the pom for the user running the build.
4. Clean and rebuild the module to rule out a stale processing environment.

Example fix

<!-- before: malformed -->
<project>
  <artifactId>quarkus-foo
</project>
<!-- after: well-formed -->
<project>
  <artifactId>quarkus-foo</artifactId>
</project>

try {
    DocumentBuilderFactory.newInstance().newDocumentBuilder()
        .parse(new File("pom.xml"));
} catch (Exception e) {
    throw new IllegalStateException("pom.xml is not valid XML: " + e.getMessage(), e);
}

try {
    build();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to parse pom file")) {
        restorePomFromVcs();
    } else throw e;
}

When it happens

Trigger: getExtensionModel is called and db.parse(pom) throws: the pom.xml at the resolved path is malformed XML, truncated, locked, or the underlying file cannot be read at annotation-processing time.

Common situations: A half-written or syntactically invalid pom (unclosed tag, wrong encoding); a build running in a workspace where the pom was edited mid-build; file permission issues or a stale/corrupt checkout.

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

• Could not resolve POM for
• Failed to parse POM
• Resolution of annotationProcessorPath dependencies failed
• Unable to update the pom.xml file
• Could not locate quarkus.properties on the classpath

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

Appendix: source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/util/ExtensionUtil.java:64

     * One option would be to pass it through the annotation processor but it's not exactly ideal.
     */
    public ExtensionModule getExtensionModule() {
        Optional<Path> pom = filerUtil.getPomPath();

        if (pom.isEmpty()) {
            return ExtensionModule.createNotDetected();
        }

        Document doc;

        try {
            DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
            dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
            DocumentBuilder db = dbf.newDocumentBuilder();
            doc = db.parse(pom.get().toFile());
            doc.getDocumentElement().normalize();
        } catch (Exception e) {
            throw new IllegalStateException("Unable to parse pom file: " + pom, e);
        }

        return getExtensionModuleFromPom(pom.get(), doc);
    }

    private ExtensionModule getExtensionModuleFromPom(Path pom, Document doc) {
        String parentGroupId = null;
        String artifactId = null;
        String groupId = null;
        String name = null;
        String guideUrl = null;

        NodeList children = doc.getDocumentElement().getChildNodes();
        for (int i = 0; i < children.getLength(); i++) {
            if (groupId != null && artifactId != null && name != null) {
                break;
            }

View on GitHub (pinned to e1c734241f)