quarkusio/quarkus · error · IllegalStateException

Unable to parse: ${javadocPath}

Error message

Unable to parse: ${javadocPath}

What it means

JavadocMerger.mergeJavadocElements reads serialized javadoc-elements JSON files and deserializes them into a JavadocRepository. When reading one of these files fails with an IOException, it is wrapped in an IllegalStateException identifying the javadoc path.

Source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/documentation/config/merger/JavadocMerger.java:40

        Map<String, JavadocElement> javadocElementsMap = new TreeMap<>();

        for (Path buildOutputDirectory : buildOutputDirectories) {
            Path javadocPath = buildOutputDirectory.resolve(Outputs.QUARKUS_CONFIG_DOC_JAVADOC);
            if (!Files.isReadable(javadocPath)) {
                continue;
            }

            try (InputStream javadocIs = Files.newInputStream(javadocPath)) {
                JavadocElements javadocElements = JacksonMappers.yamlObjectReader().forType(JavadocElements.class)
                        .readValue(javadocIs);

                if (javadocElements.elements() == null || javadocElements.elements().isEmpty()) {
                    continue;
                }

                javadocElementsMap.putAll(javadocElements.elements());
            } catch (IOException e) {
                throw new IllegalStateException("Unable to parse: " + javadocPath, e);
            }
        }

        return new JavadocRepository(javadocElementsMap);
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Clean rebuild (mvn clean install) to regenerate javadoc-elements files
2. Delete the suspicious dependency from the local repository (~/.m2) and re-resolve it
3. Align all Quarkus extension/processor versions to the same release
4. Check file permissions and JAR integrity for the reported path

if (Files.notExists(javadocPath) || Files.size(javadocPath) == 0) {
    continue; // skip missing/empty javadoc-elements files
}

try {
    return merger.mergeJavadocElements(paths);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to parse:")) {
        log.warn("Corrupt javadoc file " + e.getMessage() + "; run mvn clean install");
        throw e;
    }
    throw e;
}

When it happens

Trigger: A javadoc-elements file in a dependency JAR or generated directory is corrupted, truncated, empty-but-present, unreadable, or written by an incompatible processor version; the merger's ObjectMapper throws IOException on read.

Common situations: Mixed Quarkus versions on the annotation processor classpath (old serialized model read by newer code); partially-cached build outputs in target/; corrupted artifact in the local Maven repository.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

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

Related errors

• Could not parse HTML entity &${abbrev}; in ${text}
• Cannot initialize file manager
• Cannot reset file manager
• Unable to read the resolved model from: ${resolvedModelPath}
• Conversion from Markdown to Asciidoc is not supported

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