apple/pkl · error · PklException

Error serializing annotation for PklProject: : cannot rende

Error message

Error serializing annotation for PklProject:
:  cannot render value with unexpected type:

What it means

Thrown by DependencyMetadataWriter when serializing an annotation value whose Java type is not one of the supported generic types (String, Boolean, numbers, Duration, DataSize, Pair, collections, PObject, etc.). PClass and TypeAlias values are explicitly unsupported; the writer cannot render the value into dependency-metadata JSON and aborts with this PklException.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/DependencyMetadata.java:703

        jsonWriter.name("value").value(dataSize.getValue());
        jsonWriter.endObject();
      } else if (value instanceof Duration duration) {
        jsonWriter.beginObject();
        jsonWriter.name("type").value("Duration");
        jsonWriter.name("unit").value(duration.getUnit().getSymbol());
        jsonWriter.name("value").value(duration.getValue());
        jsonWriter.endObject();
      } else if (value instanceof Pair<?, ?> pair) {
        jsonWriter.beginObject();
        jsonWriter.name("type").value("Pair");
        jsonWriter.name("first");
        writeGenericObject(pair.getFirst());
        jsonWriter.name("second");
        writeGenericObject(pair.getSecond());
        jsonWriter.endObject();
      } else {
        // PClass and TypeAlias are not supported
        throw new PklException(
            "Error serializing annotation for PklProject:\n:"
                + "  cannot render value with unexpected type: "
                + value.getClass());
      }
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Change the annotation to use a supported value type (String, number, Duration, DataSize, Boolean, Pair, list/map of those)
Remove the unsupported annotation (PClass/TypeAlias reference) from the package's modules
Upgrade Pkl to a version that may support the value type, or file/fix the serializer to handle it

Example fix

// before
@Deprecated { replaceWith = SomeClass } // PClass value
// after
@Deprecated { replaceWith = "SomeClass" } // String value

Defensive patterns

Strategy: try-catch

Try / catch

try {
  writer.write(project);
} catch (PklException e) {
  if (e.getMessage().contains("cannot render value with unexpected type")) {
    log.error("Package contains annotations with unsupported value types (e.g. PClass/TypeAlias refs); replace them with primitives", e);
  }
}

Prevention

Use only primitive-serializable values (String, Boolean, numbers, Duration, DataSize, Pair, lists/maps) in annotations
Never use PClass or TypeAlias references as annotation values
Test `pkl project package` on the package before publishing

When it happens

Trigger: Writing PklProject dependency metadata for a package whose module annotations contain a value of an unsupported type — e.g. a PClass reference or TypeAlias used as an annotation value.

Common situations: A package author annotated properties/classes with type references or custom-class values; the metadata writer cannot flatten these to JSON, typically discovered when running pkl project package/publish or dependency resolution.

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

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