What causes "Unable to parse pom file: ${pom}" in quarkusio/quarkus?

Open the pom.xml reported in the message and validate its XML (e.g. mvn -q validate or an XML linter); fix syntax errors.

quarkusio/quarkus · error · IllegalStateException

Unable to parse pom file: ${pom}

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.

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)

Solutions

Open the pom.xml reported in the message and validate its XML (e.g. mvn -q validate or an XML linter); fix syntax errors.
Restore the pom from version control if it was corrupted: git checkout -- pom.xml.
Check file permissions/readability of the pom for the user running the build.
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>

Defensive patterns

Strategy: validation

Validate before calling

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 / catch

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

Prevention

Validate pom.xml after hand-editing it (mvn validate).
Avoid editing poms while a build is running in the same workspace.
Commit poms with correct encoding and never truncate file writes.
Use git diff/status to detect accidental pom corruption before building.

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

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