apple/pkl · error · ConversionException

Cannot convert Pkl object to Java object.%nPkl type

Error message

Cannot convert Pkl object to Java object.%nPkl type             : %s%nJava type            : %s%nMissing Pkl property : %s%nActual Pkl properties: %s

What it means

When converting a Pkl object (Composite) to a Java data object, every constructor parameter must be matched by an equally named Pkl property. This error is thrown when a required Pkl property is absent from the object being converted; the message lists the Pkl type, target Java type, the missing property name, and the properties actually present.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/PObjectToDataObject.java:196

    @Override
    public T convert(Composite value, ValueMapper valueMapper) {
      var properties = value.getProperties();
      var args = new Object[parameters.size()];
      var i = 0;

      for (var param : parameters) {
        var property = properties.get(param.first);
        if (property == null) {
          var message =
              String.format(
                  "Cannot convert Pkl object to Java object."
                      + "%nPkl type             : %s"
                      + "%nJava type            : %s"
                      + "%nMissing Pkl property : %s"
                      + "%nActual Pkl properties: %s",
                  value.getClassInfo(), targetType.getTypeName(), param.first, properties.keySet());
          throw new ConversionException(message);
        }

        try {
          var cachedPropertyType = cachedPropertyTypes[i];
          if (!cachedPropertyType.isExactClassOf(property)) {
            cachedPropertyType = PClassInfo.forValue(property);
            cachedPropertyTypes[i] = cachedPropertyType;
            cachedConverters[i] = valueMapper.getConverter(cachedPropertyType, param.second);
          }
          var cachedConverter = cachedConverters[i];
          assert cachedConverter != null;
          args[i] = cachedConverter.convert(property, valueMapper);
          i += 1;
        } catch (ConversionException e) {
          throw new ConversionException(
              String.format(
                  "Error converting property `%s` in Pkl object of type `%s` "
                      + "to equally named constructor parameter in Java class `%s`: "

View on GitHub (pinned to f3efcbfc9b)

Solutions

Add the missing property (with a value) to the Pkl object, or set a default in the Pkl class so it is always present.
Align the Java class with the Pkl schema: regenerate the data classes with pkl-codegen-java or rename the constructor parameter to match the Pkl property name.
Verify the Java constructor exposes correct parameter names (compile with -parameters or use @java.beans.ConstructorProperties) so names match the Pkl properties exactly.
If the property is genuinely optional in Java, change the Pkl type to have a default value, or write a custom Converter for the type.

Example fix

// before: Pkl object missing property
server { host = "localhost" }
// Java: Server(String host, int port)

// after: provide the missing property
server {
  host = "localhost"
  port = 8080
}

Defensive patterns

Strategy: validation

Validate before calling

// before converting, check all constructor params exist as Pkl properties
var missing = paramNames.stream()
    .filter(n -> !pklObject.getProperties().containsKey(n))
    .toList();
if (!missing.isEmpty()) throw new IllegalStateException("Missing Pkl properties: " + missing);

Try / catch

try {
  return converter.convert(pklObject, valueMapper);
} catch (ConversionException e) {
  if (e.getMessage().contains("Missing Pkl property")) {
    throw new ConfigSchemaMismatch(e.getMessage(), e);
  }
  throw e;
}

Prevention

Regenerate Java data classes with pkl-codegen-java whenever the Pkl schema changes
Give Pkl properties default values so they are always present in evaluations
Compile with -parameters or use @ConstructorProperties for reliable name matching
Add a smoke test that converts a representative Pkl object to each data class

When it happens

Trigger: Calling Converter.convert (via ValueMapper/TypeMapping) on a Pkl Composite that lacks a property whose name equals a Java constructor parameter — e.g. the Pkl module was amended/renamed, the property is nullable-and-absent, or the Java class was updated with a new constructor parameter.

Common situations: Pkl schema and Java data class drifted out of sync after code regeneration; property renamed in Pkl but not in the Java constructor; missing ConstructorProperties/@Named annotations causing a wrong parameter name that doesn't match any Pkl property; consuming a Pkl object with `...` amendments that removed a property.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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