{"record":{"id":"579d4a86200ce905","repo":"apple/pkl","slug":"invalidpropertiestoplevelvalue","errorCode":"invalidPropertiesTopLevelValue","errorMessage":"invalidPropertiesTopLevelValue","messagePattern":"invalidPropertiesTopLevelValue","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/stdlib/base/PropertiesRendererNodes.java","lineNumber":155,"sourceCode":"      cannotRenderTypeAddConverter(value);\n    }\n\n    @Override\n    public void visitNull(VmNull value) {\n      if (isDocument) {\n        writeKey();\n        writeSeparator();\n        writeLineBreak();\n      }\n    }\n\n    @Override\n    protected void visitDocument(Object value) {\n      if (!(value instanceof VmMap\n          || value instanceof VmTyped\n          || value instanceof VmMapping\n          || value instanceof VmDynamic)) {\n        throw new VmExceptionBuilder()\n            .evalError(\"invalidPropertiesTopLevelValue\", VmUtils.getClass(value))\n            .withProgramValue(\"Value\", value)\n            .build();\n      }\n      if (!isRenderDirective(value)) {\n        isDocument = true;\n      }\n      visit(value);\n    }\n\n    @Override\n    protected void visitTopLevelValue(Object value) {\n      if ((value instanceof VmMap\n              || value instanceof VmTyped\n              || value instanceof VmMapping\n              || value instanceof VmDynamic)\n          && !isRenderDirective(value)) {\n        cannotRenderTypeAddConverter((VmValue) value);","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/stdlib/base/PropertiesRendererNodes.java#L137-L173","documentation":"The Java `.properties` renderer accepts only Map, Typed, Mapping, or Dynamic values at the top level. Anything else (Listing, List, scalars) cannot be flattened into key=value properties, so the error reports the offending class.","triggerScenarios":"Rendering a Listing/List, IntSeq, or scalar as the top-level value of a `.properties` output, e.g. `output.text = myList.renderAsProperties()` where the value is not Map/Typed/Mapping/Dynamic.","commonSituations":"Producing Java properties files from Pkl but assigning a list or primitive to `output.value`; refactoring a module so `output.value` changed type from Dynamic to Listing.","solutions":["Flatten the collection into a Mapping/Dynamic with string keys, e.g. `new Mapping { [\"0\"] = x; ... }`","Use `toMap()`/key-value conversion on the listing before rendering","Render to a format that supports the value's actual type (JSON, YAML, Pcf)"],"exampleFix":"// before\noutput.value = new Listing { \"a\"; \"b\" }\noutput.renderer = new PropertiesRenderer\n// after\noutput.value = new Mapping { [\"0\"] = \"a\"; [\"1\"] = \"b\" }\noutput.renderer = new PropertiesRenderer","handlingStrategy":"validation","validationCode":"function isPropertiesTopLevel(v) { return isPklMap(v) || isPklTyped(v) || isPklMapping(v) || isPklDynamic(v); }","typeGuard":"const isPropertiesRenderable = (v) => isPklMap(v) || isPklTyped(v) || isPklMapping(v) || isPklDynamic(v);","tryCatchPattern":"try { renderAsProperties(value) } catch (e) { if (e.code === 'invalidPropertiesTopLevelValue') { /* flatten to Mapping */ } else throw e }","preventionTips":["Flatten lists into keyed mappings before properties rendering","Remember properties files are flat key=value — design output.value accordingly","Test rendering after any change to output.value type"],"tags":["pkl","renderer","properties","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"}