apple/pkl · error · ConversionException

Error converting property `%s` in Pkl object of type `%s` to

Error message

Error converting property `%s` in Pkl object of type `%s` to equally named constructor parameter in Java class `%s`: %s

What it means

This is a wrapping error: while converting each Pkl property to its corresponding Java constructor parameter, the per-property converter threw a ConversionException. pkl-config-java re-throws it with context identifying which property, Pkl type, and Java class failed, appending the original message; the root cause is available via getCause.

Source

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

                      + "%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`: "
                      + e.getMessage(),
                  param.first,
                  value.getClassInfo(),
                  Reflection.toRawType(targetType).getTypeName()),
              e.getCause());
        }
      }

      try {
        @SuppressWarnings("unchecked")
        var result = (T) constructorHandle.invokeWithArguments(args);
        return result;
      } catch (Throwable t) {
        throw new ConversionException(
            String.format("Error invoking constructor `%s`.", constructorHandle), t);

View on GitHub (pinned to f3efcbfc9b)

Solutions

Fix the offending property value in the Pkl source so it matches the Java parameter type (the message names the exact property and Pkl type).
Inspect the nested cause (e.getCause()) for the underlying conversion failure details.
Check the Pkl schema type for that property against the Java constructor parameter type and regenerate/adjust the Java class if the schema changed.
Register a custom Converter for the problematic type if the default mapping is unsuitable.

Example fix

// before: type mismatch in config
server { port = "8080" } // String, but Java expects int

// after
server { port = 8080 }

Defensive patterns

Strategy: try-catch

Try / catch

try {
  return converter.convert(pklObject, valueMapper);
} catch (ConversionException e) {
  if (e.getMessage().startsWith("Error converting property")) {
    logger.error("Config property conversion failed: " + e.getMessage());
    throw new ConfigLoadException(e.getMessage(), e.getCause());
  }
  throw e;
}

Prevention

Validate config values against the Pkl schema before mapping (evaluate the module first)
Keep Pkl property types aligned with Java constructor parameter types
Check getCause() for the underlying per-property failure
Register custom Converters for types where default mapping is lossy

When it happens

Trigger: Converter.convert on a Pkl Composite where a nested property's value cannot be converted to the matching constructor parameter type — e.g. a String that fails enum conversion, a Int that overflows the Java type, an unexpected null, or any nested ConversionException from a child converter (see errors 28/29).

Common situations: Config file contains a value of the wrong type for one field (e.g. string "8080" where an Int is expected); nested objects failing conversion deep in a hierarchy; enum strings not matching Java enum constants; version drift between Pkl schema and Java types.

Related errors

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