apple/pkl · error · IllegalArgumentException

Type mappings are not supported for array types.

Error message

Type mappings are not supported for array types.

What it means

Type mappings are only defined for class types; when either requestedType or implementationType is an array class (Class.isArray()), the constructor refuses. Array types have no type-name/parameterization semantics the mapper can handle.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/TypeMapping.java:48

public final class TypeMapping<S, T extends S> {
  public final Class<S> requestedType;
  public final Class<T> implementationType;

  private TypeMapping(Class<S> requestedType, Class<T> implementationType) {
    if (Modifier.isAbstract(implementationType.getModifiers())) {
      throw new IllegalArgumentException(
          String.format(
              "`implementationType` must not be abstract, but `%s` is.",
              implementationType.getTypeName()));
    }
    if (!requestedType.isAssignableFrom(implementationType)) {
      throw new IllegalArgumentException(
          String.format(
              "`implementationType` must be assignable to `requestedType`, but `%s` is not assignable to `%s`.",
              implementationType.getTypeName(), requestedType.getTypeName()));
    }
    if (requestedType.isArray() || implementationType.isArray()) {
      throw new IllegalArgumentException("Type mappings are not supported for array types.");
    }
    this.requestedType = requestedType;
    this.implementationType = implementationType;
  }

  public static <S, T extends S> TypeMapping<S, T> of(
      Class<S> requestedType, Class<T> implementationType) {
    return new TypeMapping<>(requestedType, implementationType);
  }

  @Override
  public boolean equals(@Nullable Object obj) {
    if (this == obj) return true;
    if (!(obj instanceof TypeMapping<?, ?> other)) return false;
    return requestedType == other.requestedType && implementationType == other.implementationType;
  }

  @Override

View on GitHub (pinned to f3efcbfc9b)

Solutions

Map to a collection type (List, Set) instead of an array.
Use the built-in collection converters (listOf, etc.) rather than a custom array mapping.
Post-process a mapped List into an array yourself after mapping.

Example fix

// before
TypeMapping.of(List.class, int[].class);
// after
TypeMapping.of(List.class, ArrayList.class);

Defensive patterns

Strategy: validation

Validate before calling

if (req.isArray() || impl.isArray()) throw new IllegalArgumentException("use collection types, not arrays");

Type guard

static boolean isNonArrayType(Class<?> c) { return !c.isArray(); }

Try / catch

try { TypeMapping.of(req, impl); } catch (IllegalArgumentException e) { /* fall back to List-based mapping */ }

Prevention

Model Pkl lists as java.util.List implementations, never arrays
Convert List results to arrays yourself after mapping if arrays are needed

When it happens

Trigger: TypeMapping.of(String[].class, ...) or TypeMapping.of(X.class, Y[].class) — either Class object represents an array.

Common situations: Trying to map Pkl lists/sequences to Java arrays; mapping Pkl `List<Int>` to int[].class instead of using the collection converters.

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/054f3b0d4cf19f1a. Report an issue: GitHub.