quarkusio/quarkus · error · MojoExecutionException

Unable to render config roots for specific file: ${fileName}

Error message

Unable to render config roots for specific file: ${fileName} in extension: ${extension}

What it means

GenerateConfigDocMojo also renders config roots stored in specific files (mergedModel.getConfigRootsInSpecificFile()). If Qute rendering or Files.writeString fails for one of these, it wraps the cause in this MojoExecutionException naming the specific file and extension. As with the top-level-prefix variant, the root cause is in the nested exception.

Source

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

            ConfigRoot configRoot = specificFileConfigRootEntry.getValue();
            Extension extension = configRoot.getExtension();

            if (configRoot.getNonDeprecatedItems().isEmpty()) {
                continue;
            }

            String normalizedFileName = stripAdocSuffix(annotationFileName);
            String fileName = normalizedFileName + "." + normalizedFormat.getExtension();

            Path configRootPath = resolvedTargetDirectory.resolve(fileName);
            String summaryTableId = formatter.toAnchor(normalizedFileName);
            Context context = new Context(summaryTableId, false);

            try {
                Files.writeString(configRootPath,
                        generateConfigReference(quteEngine, context, extension, configRoot, "", true));
            } 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());
        }

View on GitHub (pinned to e1c734241f)

Solutions

Inspect the nested cause (mvn -e) — it identifies the failing template or the IO error for that file.
Verify the output directory is writable and the fileName path is not locked/directory.
Fix the offending extension's config root definition or update the plugin templates to handle its model.
Regenerate with a matching plugin/extension version set to avoid model/template drift.

Example fix

// diagnose
mvn quarkus:generate-config-doc -e
// cause often shows e.g. io.quarkus.qute.TemplateException -> fix the config root data or template
// ensure output path writable
chmod -R u+w target/asciidoc

Defensive patterns

Strategy: try-catch

Validate before calling

if (!Files.isWritable(configRootPath.toAbsolutePath().getParent())) {
    throw new IllegalStateException("Unwritable output dir for specific file: " + fileName);
}

Try / catch

try {
    String rendered = generateConfigReference(quteEngine, context, extension, configRoot, "", true);
    Files.writeString(configRootPath, rendered);
} catch (Exception e) {
    throw new MojoExecutionException("Unable to render config roots for specific file: " + fileName, e);
}

Prevention

Inspect the wrapped cause with mvn -e; it names the template or IO failure.
Update extension config roots / plugin templates together when the config API changes.
Validate the merged model (getConfigRootsInSpecificFile) after upgrading extensions.

When it happens

Trigger: Running the generate-config-doc goal while iterating getConfigRootsInSpecificFile() when generateConfigReference(...) throws (Qute template error, bad model data) or writing configRootPath fails (unwritable path).

Common situations: Extensions that contribute config roots to dedicated doc files with shapes the templates mishandle; output directory permissions; recent config API changes breaking the generated model.

Related errors

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