{"record":{"id":"d0e0c44984a0c618","repo":"quarkusio/quarkus","slug":"one-or-more-errors-happened-during-the-configurati","errorCode":null,"errorMessage":"One or more errors happened during the configuration documentation generation. Here is a full report:\n\n","messagePattern":"One or more errors happened during the configuration documentation generation\\. Here is a full report:\n\n","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java","lineNumber":191,"sourceCode":"            } catch (Exception e) {\n                throw new MojoExecutionException(\"Unable to render config roots for specific file: \" + fileName\n                        + \" in extension: \" + extension, e);\n            }\n        }\n\n        if (!generationReport.getViolations().isEmpty()) {\n            StringBuilder report = new StringBuilder(\n                    \"One or more errors happened during the configuration documentation generation. Here is a full report:\\n\\n\");\n            for (Entry<String, List<GenerationViolation>> violationsEntry : generationReport.getViolations().entrySet()) {\n                report.append(\"- \").append(violationsEntry.getKey()).append(\"\\n\");\n                for (GenerationViolation violation : violationsEntry.getValue()) {\n                    report.append(\"    . \").append(violation.sourceElement()).append(\" - \").append(violation.message())\n                            .append(\"\\n\");\n                }\n                report.append(\"\\n----\\n\\n\");\n            }\n\n            throw new IllegalStateException(report.toString());\n        }\n\n        // we generate files for generated sections\n        for (Entry<Extension, List<ConfigSection>> extensionConfigSectionsEntry : mergedModel.getGeneratedConfigSections()\n                .entrySet()) {\n            Extension extension = extensionConfigSectionsEntry.getKey();\n\n            for (ConfigSection generatedConfigSection : extensionConfigSectionsEntry.getValue()) {\n                if (generatedConfigSection.getNonDeprecatedItems().isEmpty()) {\n                    continue;\n                }\n\n                Path configSectionPath = resolvedTargetDirectory.resolve(String.format(CONFIG_ROOT_FILE_FORMAT,\n                        extension.artifactId(), cleanSectionPath(generatedConfigSection.getPath().property()),\n                        normalizedFormat.getExtension()));\n                String summaryTableId = formatter\n                        .toAnchor(extension.artifactId() + \"_\" + generatedConfigSection.getPath().property());\n                Context context = new Context(summaryTableId, false);","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java#L173-L209","documentation":"The config-doc-maven-plugin collects all violations found while generating configuration documentation and, if any exist, throws an IllegalStateException whose message is the full formatted report of every violation. It is a fail-fast guard: documentation was generated but did not meet the plugin's consistency rules, so the build is aborted with a human-readable report instead of emitting bad docs.","triggerScenarios":"Running generate-config-doc (GenerateConfigDocMojo.execute) when the generation report contains validation violations, e.g. duplicate config property paths across extensions, undocumented options, or items whose type/javadoc metadata failed checks.","commonSituations":"Two extensions define the same config root/property path; a config mapping lacks required documentation; a Quarkus upgrade adds stricter doc checks that existing extensions fail.","solutions":["Read the appended report in the exception message; fix each listed violation.sourceElement() per its violation.message()","Search for the reported duplicate property path and rename or merge the conflicting config roots","Re-run the plugin after fixes; it only throws when the violation list is non-empty"],"exampleFix":"// before: two extensions map the same root\n@ConfigRoot(prefix = \"quarkus\")\n@ConfigMapping(prefix = \"quarkus\")\npublic interface HttpConfig {}\n// after: give the conflicting root a unique prefix\n@ConfigRoot(prefix = \"quarkus.myext\")\n@ConfigMapping(prefix = \"quarkus.myext\")\npublic interface MyExtConfig {}","handlingStrategy":"validation","validationCode":"// Preview violations before failing the build\nMergedModel model = /* build merged model as the mojo does */;\nif (!generationReport.getViolations().isEmpty()) {\n    generationReport.getViolations().forEach(v ->\n        System.out.println(v.sourceElement() + \": \" + v.message()));\n}","typeGuard":null,"tryCatchPattern":"try {\n    mojo.execute();\n} catch (IllegalStateException e) {\n    // e.getMessage() is the full violations report — parse and fix each entry\n    logger.error(\"Config doc violations:\\n\" + e.getMessage());\n}","preventionTips":["Keep config property paths unique across extensions","Document every config option per plugin rules","Run the doc generation in CI early to catch violations before release"],"tags":["maven","config-documentation","validation"],"backgroundTag":"config-doc-validation-failed","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"}