{"record":{"id":"01506004d62dc393","repo":"quarkusio/quarkus","slug":"unable-to-find-javadoc-for-config-item-enclosing","errorCode":null,"errorMessage":"Unable to find javadoc for config item ${enclosingElement} ${element}","messagePattern":"Unable to find javadoc for config item (.+?) (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/processor/src/main/java/io/quarkus/annotation/processor/util/ElementUtil.java","lineNumber":178,"sourceCode":"    public Optional<String> getJavadoc(Element e) {\n        String docComment = processingEnv.getElementUtils().getDocComment(e);\n\n        if (docComment == null || docComment.isBlank()) {\n            return Optional.empty();\n        }\n\n        // javax.lang.model keeps the leading space after the \"*\" so we need to remove it.\n\n        return Optional.of(REMOVE_LEADING_SPACE.matcher(docComment)\n                .replaceAll(\"\")\n                .trim());\n    }\n\n    public void addMissingJavadocError(Element e) {\n        String error = \"Unable to find javadoc for config item \" + e.getEnclosingElement() + \" \" + e;\n\n        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, error, e);\n        throw new IllegalStateException(error);\n    }\n\n    public boolean isJdkClass(TypeElement e) {\n        return e.getQualifiedName().toString().startsWith(\"java.\");\n    }\n}\n","sourceCodeStart":160,"sourceCodeEnd":185,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/processor/src/main/java/io/quarkus/annotation/processor/util/ElementUtil.java#L160-L185","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\nOptional<String> name();\n// after\n/**\n * The name used by the extension.\n */\nOptional<String> name();","handlingStrategy":"validation","validationCode":"for (ExecutableElement m : configInterface.getEnclosedElements()) {\n    if (m.getKind() == ElementKind.METHOD\n            && elements.getDocComment(m) == null) {\n        throw new IllegalStateException(\"Missing Javadoc on config item: \" + m);\n    }\n}","typeGuard":"boolean isDocumented(Element e, Elements elements) {\n    return e.getKind() != ElementKind.METHOD || elements.getDocComment(e) != null;\n}","tryCatchPattern":"try {\n    build();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Unable to find javadoc for config item\")) {\n        addJavadocToElementNamed(extractElementFromMessage(e));\n    } else throw e;\n}","preventionTips":["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."],"tags":["quarkus","annotation-processor","javadoc","documentation","config"],"backgroundTag":"missing-config-javadoc","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}