apple/pkl · error · RendererException

Values of type `TypeAlias` cannot be rendered as Properties.

Error message

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

What it means

The Properties (`.properties`) renderer cannot represent Pkl type-alias values, since the properties format only supports scalar string values. convertTypeAlias throws a RendererException naming the alias's simple name when one is encountered during traversal.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/PropertiesRenderer.java:178

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

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

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

    @Override
    public String convertReference(Reference value) {
      throw new RendererException(
          String.format(
              "Values of type `Reference` cannot be rendered as Properties. Value: %s", value));
    }

    private void doVisitMap(@Nullable String keyPrefix, Map<?, ?> map) {
      for (Map.Entry<?, ?> entry : map.entrySet()) {
        doVisitKeyAndValue(keyPrefix, entry.getKey(), entry.getValue());
      }
    }

    private void doVisitKeyAndValue(@Nullable String keyPrefix, Object key, Object value) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use the underlying (non-alias) primitive type for the value so it renders as a plain scalar
2. Convert the alias to its underlying value explicitly before rendering
3. Choose an output format that supports the value (json, pkl) instead of properties

Example fix

// before (Pkl)
typealias Endpoint = String
endpoint: Endpoint = "https://example.com"
// after (Pkl)
endpoint: String = "https://example.com"

// Pkl-side: ensure values are plain scalars
// if (value is TypeAlias) use value.underlyingValue (or the primitive) before rendering

try {
  renderer.render(value);
} catch (RendererException e) {
  // fall back to json/pkl output or stringify the value
}

When it happens

Trigger: Rendering output as `properties` when the value tree contains a value whose Pkl type is a type alias (e.g. `myUrl: Url` where `Url` is a `typealias String`... specifically values typed as TypeAlias), passed into PropertiesRenderer.

Common situations: Evaluating a config that uses custom type aliases for strings/URIs and then exporting to .properties files for Java tooling; migrating Java .properties templates to Pkl.

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 Properties. Val
• Maps containing non-String keys cannot be rendered as JSON.
• The top-level value of a YAML stream must have type `Collect
• Values of type `Duration` cannot be rendered as YAML. Value:
• Values of type `DataSize` cannot be rendered as YAML. Value:

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