{"record":{"id":"6c959ac823bf1f48","repo":"quarkusio/quarkus","slug":"unable-to-render-config-roots-for-specific-file","errorCode":null,"errorMessage":"Unable to render config roots for specific file: ${fileName} in extension: ${extension}","messagePattern":"Unable to render config roots for specific file: (.+?) in extension: (.+?)","errorType":"exception","errorClass":"MojoExecutionException","httpStatus":null,"severity":"error","filePath":"devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java","lineNumber":174,"sourceCode":"            ConfigRoot configRoot = specificFileConfigRootEntry.getValue();\n            Extension extension = configRoot.getExtension();\n\n            if (configRoot.getNonDeprecatedItems().isEmpty()) {\n                continue;\n            }\n\n            String normalizedFileName = stripAdocSuffix(annotationFileName);\n            String fileName = normalizedFileName + \".\" + normalizedFormat.getExtension();\n\n            Path configRootPath = resolvedTargetDirectory.resolve(fileName);\n            String summaryTableId = formatter.toAnchor(normalizedFileName);\n            Context context = new Context(summaryTableId, false);\n\n            try {\n                Files.writeString(configRootPath,\n                        generateConfigReference(quteEngine, context, extension, configRoot, \"\", true));\n            } 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        }","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java#L156-L192","documentation":"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.","triggerScenarios":"Running the generate-config-doc goal while iterating getConfigRootsInSpecificFile() when generateConfigReference(...) throws (Qute template error, bad model data) or writing configRootPath fails (unwritable path).","commonSituations":"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.","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."],"exampleFix":"// diagnose\nmvn quarkus:generate-config-doc -e\n// cause often shows e.g. io.quarkus.qute.TemplateException -> fix the config root data or template\n// ensure output path writable\nchmod -R u+w target/asciidoc","handlingStrategy":"try-catch","validationCode":"if (!Files.isWritable(configRootPath.toAbsolutePath().getParent())) {\n    throw new IllegalStateException(\"Unwritable output dir for specific file: \" + fileName);\n}","typeGuard":null,"tryCatchPattern":"try {\n    String rendered = generateConfigReference(quteEngine, context, extension, configRoot, \"\", true);\n    Files.writeString(configRootPath, rendered);\n} catch (Exception e) {\n    throw new MojoExecutionException(\"Unable to render config roots for specific file: \" + fileName, e);\n}","preventionTips":["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."],"tags":["maven-plugin","qute","config-docs","rendering"],"backgroundTag":"template-render-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}