quarkusio/quarkus · error · IllegalStateException

Unable to find javadoc for config item

Error message

Unable to find javadoc for config item ${enclosingElement} ${element}

What it means

During config documentation model generation, every config item (property/method of a config mapping) must have Javadoc so it can be rendered into the configuration reference. ElementUtil.addMissingJavadocError prints an annotation-processing ERROR at the offending element and then throws this IllegalStateException, failing the build. Quarkus requires documented config properties because the generated docs are part of the extension's contract.

Solutions

Add a Javadoc comment to every method of the config mapping interface, describing the property.
Ensure the Javadoc is on the method itself, not just the interface, and is not stripped by generation.
Rebuild the module so annotation processing re-runs and validation passes.

Example fix

// before
Optional<String> name();
// after
/**
 * The name used by the extension.
 */
Optional<String> name();

Defensive patterns

Strategy: validation

Validate before calling

for (ExecutableElement m : configInterface.getEnclosedElements()) {
    if (m.getKind() == ElementKind.METHOD
            && elements.getDocComment(m) == null) {
        throw new IllegalStateException("Missing Javadoc on config item: " + m);
    }
}

Type guard

boolean isDocumented(Element e, Elements elements) {
    return e.getKind() != ElementKind.METHOD || elements.getDocComment(e) != null;
}

Try / catch

try {
    build();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to find javadoc for config item")) {
        addJavadocToElementNamed(extractElementFromMessage(e));
    } else throw e;
}

Prevention

Write the Javadoc when adding each config property — make it part of the property's definition.
Enable strict Javadoc checks in CI so missing docs fail before annotation processing does.
Never delete Javadoc when renaming or moving config properties.
Run a doc build (./mvnw in the extension) before opening the PR.

When it happens

Trigger: Compiling an extension whose @ConfigMapping interface method (config item) has no Javadoc comment, when the processor's documentation generation walks the element and finds no doc comment attached.

Common situations: Adding a new config property quickly and skipping the Javadoc; renaming/moving a property and losing its comment; generated or overridden methods missing docs; building with -DskipDocs disabled (default docs generation path).

Related errors

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

Appendix: source

Thrown at core/processor/src/main/java/io/quarkus/annotation/processor/util/ElementUtil.java:178

    public Optional<String> getJavadoc(Element e) {
        String docComment = processingEnv.getElementUtils().getDocComment(e);

        if (docComment == null || docComment.isBlank()) {
            return Optional.empty();
        }

        // javax.lang.model keeps the leading space after the "*" so we need to remove it.

        return Optional.of(REMOVE_LEADING_SPACE.matcher(docComment)
                .replaceAll("")
                .trim());
    }

    public void addMissingJavadocError(Element e) {
        String error = "Unable to find javadoc for config item " + e.getEnclosingElement() + " " + e;

        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, error, e);
        throw new IllegalStateException(error);
    }

    public boolean isJdkClass(TypeElement e) {
        return e.getQualifiedName().toString().startsWith("java.");
    }
}

View on GitHub (pinned to e1c734241f)