apple/pkl · error · IllegalArgumentException

`%s.class` is not a valid type argument. Did you mean `%s.cl

Error message

`%s.class` is not a valid type argument. Did you mean `%s.class`?

What it means

Java generics cannot use primitives as type arguments (List<int> is illegal). When parameterizedType() sees a primitive Class among the type arguments, it throws and suggests the corresponding wrapper class from Reflection.toWrapperType.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/Types.java:49

  public static ParameterizedType parameterizedType(Class<?> rawType, Type... typeArguments) {
    var typeParamsCount = rawType.getTypeParameters().length;
    if (typeParamsCount == 0) {
      throw new IllegalArgumentException(
          String.format(
              "Cannot parameterize `%s` because it does not have any type parameters.",
              rawType.getTypeName()));
    }
    if (typeArguments.length != typeParamsCount) {
      throw new IllegalArgumentException(
          String.format(
              "Expected %d type arguments for `%s`, but got %d.",
              typeParamsCount, rawType.getTypeName(), typeArguments.length));
    }
    for (Type arg : typeArguments) {
      if (arg instanceof Class<?> clazz) {
        if (clazz.isPrimitive()) {
          throw new IllegalArgumentException(
              String.format(
                  "`%s.class` is not a valid type argument. Did you mean `%s.class`?",
                  clazz, Reflection.toWrapperType(clazz).getSimpleName()));
        }
      }
    }
    try {
      return (ParameterizedType) TypeFactory.parameterizedClass(rawType, typeArguments);
    } catch (TypeArgumentNotInBoundException e) {
      throw new IllegalArgumentException(
          String.format(
              "Type argument `%s` for type parameter `%s` is not within bound `%s`.",
              e.getArgument().getTypeName(),
              e.getParameter().getTypeName(),
              e.getBound().getTypeName()));
    }
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

Replace the primitive .class literal with its wrapper: Integer.class, Long.class, Double.class, Boolean.class, etc.
Use Pkl's boxed types for numeric Pkl properties.
Scan your typeArguments array for isPrimitive() before calling.

Example fix

// before
Types.parameterizedType(List.class, int.class);
// after
Types.parameterizedType(List.class, Integer.class);

Defensive patterns

Strategy: validation

Validate before calling

for (Type a : args) if (a instanceof Class<?> c && c.isPrimitive()) throw new IllegalArgumentException("use wrapper for " + c);

Type guard

static boolean isBoxed(Type t) { return !(t instanceof Class<?> c && c.isPrimitive()); }

Try / catch

try { Types.parameterizedType(raw, args); } catch (IllegalArgumentException e) { /* switch to wrapper classes */ }

Prevention

Always use Integer/Long/Double/Boolean.class as type arguments
Centralize type-argument construction so primitive literals cannot sneak in

When it happens

Trigger: parameterizedType(List.class, int.class), parameterizedType(Map.class, String.class, double.class) — any arg where clazz.isPrimitive() is true.

Common situations: Mapping Pkl Int to int.class instead of Integer.class, or Float/Boolean similarly; auto-completed .class literals defaulting to primitives.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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