{"record":{"id":"89f90e5f3f8ea140","repo":"apple/pkl","slug":"invalidyamlstreamtoplevelvalue","errorCode":"invalidYamlStreamTopLevelValue","errorMessage":"invalidYamlStreamTopLevelValue","messagePattern":"invalidYamlStreamTopLevelValue","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/stdlib/base/YamlRendererNodes.java","lineNumber":139,"sourceCode":"            }));\n        return;\n      }\n\n      if (value instanceof VmCollection collection) {\n        var first = true;\n        for (var element : collection) {\n          if (first) {\n            first = false;\n          } else {\n            startNewLine();\n            builder.append(\"---\");\n          }\n          visit(element);\n        }\n        return;\n      }\n\n      throw new VmExceptionBuilder()\n          .evalError(\"invalidYamlStreamTopLevelValue\", VmUtils.getClass(value))\n          .withProgramValue(\"Value\", value)\n          .build();\n    }\n\n    @Override\n    public void visitTopLevelValue(Object value) {\n      visit(value);\n    }\n\n    @Override\n    public void visitString(String value) {\n      if (!builder.isEmpty()) builder.append(' ');\n      emitter.emit(value, currIndent, false);\n    }\n\n    @Override\n    public void visitInt(Long value) {","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/stdlib/base/YamlRendererNodes.java#L121-L157","documentation":"The YAML renderer, when emitting a multi-document YAML stream, requires the top-level value to be a Listing (or List) whose elements are each renderable documents. A non-listing top-level value cannot form a YAML stream, so the error names the class found instead.","triggerScenarios":"Using `YamlRenderer` with stream mode (e.g. `renderAsYamlStream()` or a renderer configured for streams) on a Mapping, Dynamic, Typed object, or scalar instead of a Listing/List of documents.","commonSituations":"Emitting multi-document YAML for Kubernetes-style configs but passing a single object or map as `output.value`; switching a renderer from document to stream mode without changing the value.","solutions":["Wrap the value in a `Listing` (or `List`), e.g. `new Listing { obj1; obj2 }`","If only one document is needed, use the non-stream YAML renderer instead","Ensure each stream element is itself a valid YAML document value"],"exampleFix":"// before\noutput.value = new Dynamic { name = \"a\" }\noutput.renderer = new YamlRenderer { stream = true }\n// after\noutput.value = new Listing { new Dynamic { name = \"a\" } }\noutput.renderer = new YamlRenderer { stream = true }","handlingStrategy":"validation","validationCode":"function isYamlStreamTopLevel(v) { return isPklListing(v) || Array.isArray(v); }","typeGuard":"const isYamlStreamRenderable = (v) => isPklListing(v) || isPklList(v);","tryCatchPattern":"try { renderAsYamlStream(value) } catch (e) { if (e.code === 'invalidYamlStreamTopLevelValue') { /* wrap in Listing */ } else throw e }","preventionTips":["Use stream mode only with Listing/List top-level values","Wrap single documents in a one-element Listing","Match renderer stream flag to the value's shape"],"tags":["pkl","renderer","yaml","stream"],"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"}