quarkusio/quarkus · error · IllegalStateException

One or more errors happened during the configuration documen

Error message

One or more errors happened during the configuration documentation generation. Here is a full report:

What it means

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.

Source

Thrown at devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java:191

            } catch (Exception e) {
                throw new MojoExecutionException("Unable to render config roots for specific file: " + fileName
                        + " in extension: " + extension, e);
            }
        }

        if (!generationReport.getViolations().isEmpty()) {
            StringBuilder report = new StringBuilder(
                    "One or more errors happened during the configuration documentation generation. Here is a full report:\n\n");
            for (Entry<String, List<GenerationViolation>> violationsEntry : generationReport.getViolations().entrySet()) {
                report.append("- ").append(violationsEntry.getKey()).append("\n");
                for (GenerationViolation violation : violationsEntry.getValue()) {
                    report.append("    . ").append(violation.sourceElement()).append(" - ").append(violation.message())
                            .append("\n");
                }
                report.append("\n----\n\n");
            }

            throw new IllegalStateException(report.toString());
        }

        // we generate files for generated sections
        for (Entry<Extension, List<ConfigSection>> extensionConfigSectionsEntry : mergedModel.getGeneratedConfigSections()
                .entrySet()) {
            Extension extension = extensionConfigSectionsEntry.getKey();

            for (ConfigSection generatedConfigSection : extensionConfigSectionsEntry.getValue()) {
                if (generatedConfigSection.getNonDeprecatedItems().isEmpty()) {
                    continue;
                }

                Path configSectionPath = resolvedTargetDirectory.resolve(String.format(CONFIG_ROOT_FILE_FORMAT,
                        extension.artifactId(), cleanSectionPath(generatedConfigSection.getPath().property()),
                        normalizedFormat.getExtension()));
                String summaryTableId = formatter
                        .toAnchor(extension.artifactId() + "_" + generatedConfigSection.getPath().property());
                Context context = new Context(summaryTableId, false);

View on GitHub (pinned to e1c734241f)

Solutions

  1. Read the appended report in the exception message; fix each listed violation.sourceElement() per its violation.message()
  2. Search for the reported duplicate property path and rename or merge the conflicting config roots
  3. Re-run the plugin after fixes; it only throws when the violation list is non-empty

Example fix

// before: two extensions map the same root
@ConfigRoot(prefix = "quarkus")
@ConfigMapping(prefix = "quarkus")
public interface HttpConfig {}
// after: give the conflicting root a unique prefix
@ConfigRoot(prefix = "quarkus.myext")
@ConfigMapping(prefix = "quarkus.myext")
public interface MyExtConfig {}
Defensive patterns

Strategy: validation

Validate before calling

// Preview violations before failing the build
MergedModel model = /* build merged model as the mojo does */;
if (!generationReport.getViolations().isEmpty()) {
    generationReport.getViolations().forEach(v ->
        System.out.println(v.sourceElement() + ": " + v.message()));
}

Try / catch

try {
    mojo.execute();
} catch (IllegalStateException e) {
    // e.getMessage() is the full violations report — parse and fix each entry
    logger.error("Config doc violations:\n" + e.getMessage());
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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