{"record":{"id":"8e9abc3f805eccdd","repo":"apple/pkl","slug":"invalidplisttoplevelvalue","errorCode":"invalidPListTopLevelValue","errorMessage":"invalidPListTopLevelValue","messagePattern":"invalidPListTopLevelValue","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/stdlib/base/PListRendererNodes.java","lineNumber":162,"sourceCode":"          .build();\n    }\n\n    @Override\n    public void visitPair(VmPair value) {\n      cannotRenderTypeAddConverter(value);\n    }\n\n    @Override\n    public void visitNull(VmNull value) {\n      cannotRenderTypeAddConverter(value);\n    }\n\n    @Override\n    protected void visitDocument(Object value) {\n      if (!(value instanceof VmCollection\n          || value instanceof VmMap\n          || value instanceof VmObjectLike)) {\n        throw new VmExceptionBuilder()\n            .evalError(\"invalidPListTopLevelValue\", VmUtils.getClass(value))\n            .withProgramValue(\"Value\", value)\n            .build();\n      }\n      builder\n          .append(\"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\")\n          .append(LINE_BREAK)\n          .append(\n              \"<!DOCTYPE plist PUBLIC \\\"-//Apple//DTD PLIST 1.0//EN\\\" \\\"http://www.apple.com/DTDs/PropertyList-1.0.dtd\\\">\")\n          .append(LINE_BREAK)\n          .append(\"<plist version=\\\"1.0\\\">\")\n          .append(LINE_BREAK);\n\n      visit(value);\n\n      builder.append(LINE_BREAK).append(\"</plist>\").append(LINE_BREAK);\n    }\n","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/stdlib/base/PListRendererNodes.java#L144-L180","documentation":"The XML property list renderer only accepts top-level values that are collections, maps, or object-like values (typed/dynamic/module objects). Any other top-level value (e.g. a bare String, Int, or IntSeq) cannot be represented as a plist document, so this error is thrown naming the class.","triggerScenarios":"Rendering a scalar or unsupported value (e.g. `\"hello\"`, `42`) as the top-level value of a plist output; using `render()` on a value whose class is not VmCollection, VmMap, or VmObjectLike.","commonSituations":"Wrapping a primitive in `output.value` and rendering to `.plist`; rendering a module whose `output.value` resolves to a scalar instead of an object or mapping.","solutions":["Wrap the scalar in a `Dynamic` or `Mapping`, e.g. `new Dynamic { value = 42 }`","Use `new Mapping { ... }` or a typed object as the top-level value","Switch output format to one that supports scalars (e.g. Pcf, JSON)"],"exampleFix":"// before\noutput.value = 42\noutput.renderer = new PListRenderer\n// after\noutput.value = new Dynamic { answer = 42 }\noutput.renderer = new PListRenderer","handlingStrategy":"validation","validationCode":"function isPlistTopLevel(v) { return v instanceof Object || v instanceof Map || Array.isArray(v) === false && isPklObjectLike(v); }","typeGuard":"const isPlistRenderable = (v) => isPklCollection(v) || isPklMap(v) || isPklObjectLike(v);","tryCatchPattern":"try { renderAsPList(value) } catch (e) { if (e.code === 'invalidPListTopLevelValue') { /* wrap in Dynamic and retry */ } else throw e }","preventionTips":["Never assign bare scalars to output.value when rendering plist","Wrap scalars in Dynamic/Mapping in the module itself","Snapshot-test rendered output for each renderer you use"],"tags":["pkl","renderer","plist","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"}