apple/pkl · error · VmException

expectedAnnotationClass

expectedAnnotationClass

Error message

Expected an annotation class.

What it means

An annotation position (e.g. `@Type` style usage via this node) expected a class that is a subclass of `Annotation`, but the given type resolved to a non-annotation class. Pkl only permits `@AnnotationClass` in annotation positions.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/literal/CheckIsAnnotationClassNode.java:50

    this.unresolvedTypeNode = unresolvedTypeNode;
  }

  @Override
  public Object executeGeneric(VirtualFrame frame) {
    if (typeNode == null) {
      // invalidation is done by insert()
      CompilerDirectives.transferToInterpreter();
      assert unresolvedTypeNode != null;
      typeNode = insert(unresolvedTypeNode.execute(frame));
      unresolvedTypeNode = null;
    }
    var clazz = typeNode.getVmClass();
    if (clazz != null && clazz.isSubclassOf(BaseModule.getAnnotationClass())) {
      return typeNode.getVmClass();
    }

    CompilerDirectives.transferToInterpreter();
    throw exceptionBuilder().evalError("expectedAnnotationClass").build();
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Declare the class as an annotation class: `annotation class Foo`.
2. Use a built-in annotation like `@Deprecated` or a project-defined annotation class.
3. Check imports — the name may resolve to a non-annotation class in another module.

Example fix

// before
class MyAnno
@MyAnno property x: Int
// after
annotation class MyAnno
@MyAnno property x: Int

// verify the symbol is an annotation class before use
// annotation class MyAnno

function isAnnotationClass(c) { return c != null && c is Class && c.isSubclassOf(Annotation); }

When it happens

Trigger: Writing `@SomeClass` where `SomeClass` is a regular class, module import, or type alias that is not declared as `annotation class SomeClass`.

Common situations: Typo in annotation name, annotating with a plain `class` instead of an `annotation class`, or importing the wrong symbol with the same name.

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

• Values of type `Class` cannot be rendered as YAML. Value: %s
• cannotInstantiateAbstractClass
• cannotInstantiateExternalClass
• moduleIsNotConstAnnotation
• cannotInvokeSupermethodFromHere

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