{"record":{"id":"c965bb56ae92e295","repo":"apple/pkl","slug":"the-top-level-value-of-a-yaml-stream-must-have-typ","errorCode":null,"errorMessage":"The top-level value of a YAML stream must have type `Collection`, but got type `%s`.","messagePattern":"The top-level value of a YAML stream must have type `Collection`, but got type `(.+?)`\\.","errorType":"exception","errorClass":"RendererException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/YamlRenderer.java","lineNumber":92,"sourceCode":"              @Override\n              public void write(String str, int off, int len) {\n                try {\n                  writer.write(str, off, len);\n                } catch (IOException e) {\n                  throw new UncheckedIOException(e);\n                }\n              }\n            });\n\n    this.omitNullProperties = omitNullProperties;\n    this.isStream = isStream;\n  }\n\n  @Override\n  public void renderDocument(Object value) {\n    if (isStream) {\n      if (!(value instanceof Iterable<?> iterable)) {\n        throw new RendererException(\n            String.format(\n                \"The top-level value of a YAML stream must have type `Collection`, but got type `%s`.\",\n                value.getClass().getTypeName()));\n      }\n      emitter.emit(new StreamStartEvent());\n      for (var elem : iterable) {\n        emitter.emit(new DocumentStartEvent(false, Optional.empty(), Map.of()));\n        visitor.visit(elem);\n        emitter.emit(new DocumentEndEvent(false));\n      }\n      emitter.emit(new StreamEndEvent());\n    } else {\n      // a top-level YAML value can have any type\n      renderValue(value);\n    }\n  }\n\n  @Override","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/YamlRenderer.java#L74-L110","documentation":"YamlRenderer.renderDocument, when rendering a YAML stream (isStream == true), requires the top-level value to be an Iterable so it can emit each element as a separate YAML document. Any other type throws RendererException stating the actual type name.","triggerScenarios":"Creating a YamlRenderer with setStream(true) (or stream output mode) and calling renderDocument with a non-collection value such as a Mapping, List without Iterable at that level, String, or Number.","commonSituations":"Rendering a single Pkl object to YAML with stream mode accidentally enabled; CLI `pkl eval -f yaml` with a stream-flavored output when the module's output value is not a list.","solutions":["Disable stream mode (renderer.setStream(false)) if you want a single YAML document.","Wrap the value in a List before rendering when stream output is required.","Change the Pkl module's output value to a List/Iterable so each element becomes its own document."],"exampleFix":"// before\nrenderer.setStream(true);\nrenderer.renderDocument(mapping); // throws\n// after\nrenderer.setStream(false);\nrenderer.renderDocument(mapping);","handlingStrategy":"type-guard","validationCode":"if (isStream && !(value instanceof Iterable)) {\n  throw new IllegalArgumentException(\"stream output requires a top-level list\");\n}","typeGuard":"boolean isRenderableStreamRoot(Object v) { return v instanceof Iterable<?>; }","tryCatchPattern":"try {\n  renderer.renderDocument(value);\n} catch (RendererException e) {\n  if (e.getMessage().contains(\"YAML stream must have type `Collection`\")) {\n    renderer.renderDocument(List.of(value)); // or disable stream mode\n  } else throw e;\n}","preventionTips":["Match stream mode to the data shape: enable isStream only for list outputs.","Normalize non-list roots by wrapping in List.of(...) before rendering.","Assert the top-level output type in tests for each output format."],"tags":["yaml","rendering","pkl","type-mismatch"],"backgroundTag":"type-mismatch","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"}