apple/pkl · error · VmException

invalidPListTopLevelValue

invalidPListTopLevelValue

Error message

invalidPListTopLevelValue

What it means

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.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/PListRendererNodes.java:162

          .build();
    }

    @Override
    public void visitPair(VmPair value) {
      cannotRenderTypeAddConverter(value);
    }

    @Override
    public void visitNull(VmNull value) {
      cannotRenderTypeAddConverter(value);
    }

    @Override
    protected void visitDocument(Object value) {
      if (!(value instanceof VmCollection
          || value instanceof VmMap
          || value instanceof VmObjectLike)) {
        throw new VmExceptionBuilder()
            .evalError("invalidPListTopLevelValue", VmUtils.getClass(value))
            .withProgramValue("Value", value)
            .build();
      }
      builder
          .append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>")
          .append(LINE_BREAK)
          .append(
              "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">")
          .append(LINE_BREAK)
          .append("<plist version=\"1.0\">")
          .append(LINE_BREAK);

      visit(value);

      builder.append(LINE_BREAK).append("</plist>").append(LINE_BREAK);
    }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Wrap the scalar in a `Dynamic` or `Mapping`, e.g. `new Dynamic { value = 42 }`
2. Use `new Mapping { ... }` or a typed object as the top-level value
3. Switch output format to one that supports scalars (e.g. Pcf, JSON)

Example fix

// before
output.value = 42
output.renderer = new PListRenderer
// after
output.value = new Dynamic { answer = 42 }
output.renderer = new PListRenderer

function isPlistTopLevel(v) { return v instanceof Object || v instanceof Map || Array.isArray(v) === false && isPklObjectLike(v); }

const isPlistRenderable = (v) => isPklCollection(v) || isPklMap(v) || isPklObjectLike(v);

try { renderAsPList(value) } catch (e) { if (e.code === 'invalidPListTopLevelValue') { /* wrap in Dynamic and retry */ } else throw e }

When it happens

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

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

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

• cannotRenderType
• invalidPcfTopLevelValue
• invalidPropertiesTopLevelValue
• invalidProtobufTopLevelValue
• Values of type `Duration` cannot be rendered as JSON. Value:

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