{"record":{"id":"22422e4e78b06600","repo":"apple/pkl","slug":"invalidpcftoplevelvalue","errorCode":"invalidPcfTopLevelValue","errorMessage":"invalidPcfTopLevelValue","messagePattern":"invalidPcfTopLevelValue","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/stdlib/base/PcfRenderer.java","lineNumber":152,"sourceCode":"    builder.append(VmUtils.readTextProperty(value));\n  }\n\n  private void visitPcfRenderDirective(VmTyped value) {\n    var before = VmUtils.readMember(value, Identifier.BEFORE);\n    if (before instanceof String string) { // not VmNull\n      builder.append(string);\n    }\n    visit(VmUtils.readMember(value, Identifier.VALUE));\n    var after = VmUtils.readMember(value, Identifier.AFTER);\n    if (after instanceof String string) { // not VmNull\n      builder.append(string);\n    }\n  }\n\n  @Override\n  protected void visitDocument(Object value) {\n    if (!(value instanceof VmTyped || value instanceof VmDynamic)) {\n      throw new VmExceptionBuilder()\n          .evalError(\"invalidPcfTopLevelValue\", VmUtils.getClass(value))\n          .withProgramValue(\"Value\", value)\n          .build();\n    }\n    isDocument = true;\n    topLevelValue = value;\n    visit(value);\n    if (!builder.isEmpty()) {\n      builder.append('\\n');\n    }\n  }\n\n  @Override\n  protected void visitTopLevelValue(Object value) {\n    topLevelValue = value;\n    visit(value);\n  }\n","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/stdlib/base/PcfRenderer.java#L134-L170","documentation":"The Pcf renderer requires the top-level value to be a typed object (`VmTyped`) or `Dynamic`. Rendering any other value (Mapping, List, Map, scalar) as a Pcf document is invalid, so the error names the actual class encountered.","triggerScenarios":"Setting `output.renderer = new PcfRenderer` (or `output.text = value.renderAsPcf()`) where the value is a Mapping, Listing, Map, List, or primitive rather than a typed object or Dynamic.","commonSituations":"Rendering a `Mapping` or `Listing` to Pcf; accidentally assigning `output.value` to a collection when Pcf output expects an object-like value.","solutions":["Convert the value to `Dynamic` or a typed object, e.g. `new Dynamic { ... }` or `new { ... }`","If it is a Mapping/Listing, wrap or convert it (`toDynamic()` style) before rendering","Choose a renderer that accepts the value's shape (e.g. JSON/YAML renderer for maps and lists)"],"exampleFix":"// before\noutput.value = new Mapping { [\"a\"] = 1 }\noutput.renderer = new PcfRenderer\n// after\noutput.value = new Dynamic { a = 1 }\noutput.renderer = new PcfRenderer","handlingStrategy":"validation","validationCode":"function isPcfTopLevel(v) { return isPklTyped(v) || isPklDynamic(v); }","typeGuard":"const isPcfRenderable = (v) => isPklTyped(v) || isPklDynamic(v);","tryCatchPattern":"try { renderAsPcf(value) } catch (e) { if (e.code === 'invalidPcfTopLevelValue') { /* convert to Dynamic */ } else throw e }","preventionTips":["Ensure output.value is a typed object or Dynamic when using PcfRenderer","Avoid Mapping/Listing as top-level Pcf values","Validate output value shape in CI by rendering all modules"],"tags":["pkl","renderer","pcf","top-level-value"],"backgroundTag":"unsupported-operation","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}