apple/pkl · error · VmException

cannotDeclareTypeParameter

cannotDeclareTypeParameter

Error message

cannotDeclareTypeParameter

What it means

Pkl only allows declaring type parameters (`<T>`, `<out T>`) in type aliases (`typealias X<T> = ...`) and in the standard library modules. Anywhere else a type parameter list appears, the AST builder rejects it, since Pkl classes and functions are not generic in user code.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:2297

      nodes[i] = visitAnnotation(annotations.get(i), annotatedMemberName);
    }
    return nodes;
  }

  public UnresolvedTypeNode visitType(Type type) {
    return (UnresolvedTypeNode) type.accept(this);
  }

  public ExpressionNode visitExpr(Expr expr) {
    return (ExpressionNode) expr.accept(this);
  }

  @Override
  public List<TypeParameter> visitTypeParameterList(@Nullable TypeParameterList ctx) {
    if (ctx == null) return List.of();

    if (!(ctx.parent() instanceof TypeAlias) && !isStdLibModule) {
      throw exceptionBuilder()
          .evalError("cannotDeclareTypeParameter")
          .withSourceSection(createSourceSection(ctx.getParameters().get(0)))
          .build();
    }

    var params = ctx.getParameters();
    var size = params.size();
    var result = new ArrayList<TypeParameter>(size);
    for (var i = 0; i < size; i++) {
      var paramCtx = params.get(i);
      Variance variance;
      var nodeVariance = paramCtx.getVariance();
      if (nodeVariance == null) {
        variance = TypeParameter.Variance.INVARIANT;
      } else {
        variance =
            switch (nodeVariance) {
              case IN -> TypeParameter.Variance.CONTRAVARIANT;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Remove the type parameter list; use `Any` or a union type instead, e.g. `class Box { value: Any }`.
2. Put the abstraction in a type alias if a parametric alias fits: `typealias Pair<K, V> = Mapping<K, V>`.
3. If you truly need generics in stdlib-style code, contribute/use the stdlib path (not available to user modules).

Example fix

// before
class Box<T> { value: T }
// after
class Box { value: Any }
// or
typealias BoxOf<T> = Mapping<String, T>

// reject generic class/function syntax before submitting to Pkl
if (/\b(class|function)\s+\w+\s*</.test(src))
  throw new Error('Pkl only supports type parameters in typealias declarations');

When it happens

Trigger: Writing a type parameter list on a class, method, or property outside stdlib, e.g. `class Box<T> { ... }` or `function identity<T>(x: T): T`. The guard checks `!(ctx.parent instanceof TypeAlias) && !isStdLibModule` in visitTypeParameterList.

Common situations: Coming from Java/Kotlin/TypeScript generics and assuming Pkl classes are generic; attempting to write a generic collection class in application config code.

Related errors

• duplicateTypeParameter
• JavaType token must be parameterized.
• wrongTypeArgumentCount
• abstractMemberCannotHaveBody
• missingMethodBody

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