apple/pkl · error · VmException

invalidYamlStreamTopLevelValue

invalidYamlStreamTopLevelValue

Error message

invalidYamlStreamTopLevelValue

What it means

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.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/YamlRendererNodes.java:139

            }));
        return;
      }

      if (value instanceof VmCollection collection) {
        var first = true;
        for (var element : collection) {
          if (first) {
            first = false;
          } else {
            startNewLine();
            builder.append("---");
          }
          visit(element);
        }
        return;
      }

      throw new VmExceptionBuilder()
          .evalError("invalidYamlStreamTopLevelValue", VmUtils.getClass(value))
          .withProgramValue("Value", value)
          .build();
    }

    @Override
    public void visitTopLevelValue(Object value) {
      visit(value);
    }

    @Override
    public void visitString(String value) {
      if (!builder.isEmpty()) builder.append(' ');
      emitter.emit(value, currIndent, false);
    }

    @Override
    public void visitInt(Long value) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Wrap the value in a `Listing` (or `List`), e.g. `new Listing { obj1; obj2 }`
2. If only one document is needed, use the non-stream YAML renderer instead
3. Ensure each stream element is itself a valid YAML document value

Example fix

// before
output.value = new Dynamic { name = "a" }
output.renderer = new YamlRenderer { stream = true }
// after
output.value = new Listing { new Dynamic { name = "a" } }
output.renderer = new YamlRenderer { stream = true }

function isYamlStreamTopLevel(v) { return isPklListing(v) || Array.isArray(v); }

const isYamlStreamRenderable = (v) => isPklListing(v) || isPklList(v);

try { renderAsYamlStream(value) } catch (e) { if (e.code === 'invalidYamlStreamTopLevelValue') { /* wrap in Listing */ } else throw e }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Values of type `Duration` cannot be rendered as JSON. Value:
• Values of type `DataSize` cannot be rendered as JSON. Value:
• Values of type `Bytes` cannot be rendered as JSON. Value: %s
• The top-level value of a YAML stream must have type `Collect
• Values of type `Duration` cannot be rendered as YAML. Value:

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/89f90e5f3f8ea140. Report an issue: GitHub.