apple/pkl · error · RendererException

Values of type `TypeAlias` cannot be rendered as YAML. Value

Error message

Values of type `TypeAlias` cannot be rendered as YAML. Value: %s

What it means

Pkl's YAML renderer (YamlRenderer) only knows how to serialize concrete Pkl values (objects, lists, primitives) to YAML. When the value being rendered is a TypeAlias — a named alias for another type rather than a runtime value — there is no valid YAML representation, so visitTypeAlias throws a RendererException. This is a defensive guard: the renderer is being asked to output something that is a type-level, not value-level, entity.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/YamlRenderer.java:210

      doVisitProperties(value.getProperties());
    }

    @Override
    public void visitModule(PModule value) {
      doVisitProperties(value.getProperties());
    }

    @Override
    public void visitClass(PClass value) {
      throw new RendererException(
          String.format(
              "Values of type `Class` cannot be rendered as YAML. Value: %s",
              value.getSimpleName()));
    }

    @Override
    public void visitTypeAlias(TypeAlias value) {
      throw new RendererException(
          String.format(
              "Values of type `TypeAlias` cannot be rendered as YAML. Value: %s",
              value.getSimpleName()));
    }

    @Override
    public void visitNull() {
      emitter.emit(YamlUtils.plainScalar("null", Tag.NULL));
    }

    @Override
    public void visitRegex(Pattern value) {
      throw new RendererException(
          String.format("Values of type `Regex` cannot be rendered as YAML. Value: %s", value));
    }

    private void doVisitIterable(Iterable<?> iterable, @Nullable String tag) {
      emitter.emit(

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Find the property/expression whose value is a TypeAlias and replace it with an actual value of that type (e.g. instantiate the aliased type).
2. If you intend to render type metadata, render its name/text instead of the alias object itself (e.g. value.getSimpleName() or a String property).
3. Filter out non-value members (classes, type aliases, modules) before feeding values to the YAML renderer.
4. Check whether a lookup by name picked the wrong module member (alias vs. instance) and disambiguate.

Example fix

// before (Pkl)
outputText = renderer.renderDocument(myAlias)
// after
outputText = renderer.renderDocument(myValue) // an instance conforming to the alias, not the alias itself

// Kotlin/Java caller
if (value is org.pkl.core.runtime.VmValue && value.getVmClass() is VmTypeAlias) {
  throw IllegalArgumentException("Cannot render type alias ${value.getVmClass().getSimpleName()} as YAML")
}

fun isRenderableValue(v: Any?): Boolean = when (v) {
  null, is String, is Boolean, is Number, is List<*>, is Map<*, *> -> true
  else -> v is org.pkl.core.runtime.VmValue && v.getVmClass() !is VmTypeAlias && v.getVmClass() !is VmClass
}

When it happens

Trigger: Passing a reference to a Pkl type alias (or a module/class/type-alias object) into YAML rendering, e.g. rendering a property whose value is a type alias instead of an instance, or calling the renderer/YAML emitter on non-data values like `Int`-style aliases.

Common situations: Config mistakes where a pkl property was declared with a type alias but assigned the alias itself instead of a value; tooling that walks a module and renders every declared member as YAML; dynamic code that resolved a module member by name and got the alias object rather than an instance.

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 `Regex` cannot be rendered as YAML. Value: %s
• invalidYamlStreamTopLevelValue
• Type mappings are not supported for array types.
• Values of type `Duration` cannot be rendered as JSON. Value:
• Values of type `DataSize` cannot be rendered as JSON. Value:

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