apple/pkl · error · RendererException

Values of type `Regex` cannot be rendered as Properties. Val

Error message

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

What it means

The Properties renderer also rejects Pkl Regex values; the .properties format has no way to express a regex literal, so convertRegex throws a RendererException. Similarly convertReference rejects Reference values. Both are thrown eagerly during property traversal.

Source

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

    @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) {
      if (omitNullProperties && value instanceof PNull) return;

      var keyString = keyPrefix == null ? convert(key) : keyPrefix + "." + convert(key);

      if (value instanceof Composite composite) {
        doVisitMap(keyString, composite.getProperties());
      } else if (value instanceof Map<?, ?> map) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Store the pattern as its String source in the config (`pattern: String = "[a-z]+"`) and build Regex at the consumer
2. Convert the Regex to its string representation before rendering to properties
3. Pick a format that supports regex values (json, pkl) instead of properties

Example fix

// before (Pkl)
pattern = Regex("[a-z]+")
// after (Pkl)
pattern = "[a-z]+" // build Regex on the consumer side

// Pkl-side: declare pattern as String
pattern: String = "[a-z]+"

try {
  renderer.render(value);
} catch (RendererException e) {
  // convert Regex values to their string source or switch output format
}

When it happens

Trigger: Rendering output as `properties` when the value tree contains a Regex value (a `Regex(...)` pattern) or a lazily-referenced Reference value.

Common situations: Config files that define regex validation patterns (e.g. `pattern = Regex("[a-z]+")`) exported to .properties for a legacy Java consumer; switching an existing output renderer from json to properties without auditing value types.

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 `TypeAlias` cannot be rendered as Properties.
• Failed to convert `pkl.base#String` to `java.util.regex.Patt
• 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:

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