apple/pkl · error · VmTypeMismatchException

type mismatch: value is not an instance of expected supercla

Error message

type mismatch: value is not an instance of expected superclass

What it means

Pkl superclass type check failure (cached specialization). The expected type is a (non-final) class and the check `clazz.isSuperclassOf(cachedClass)`/`isSuperclassOf(value.getVmClass())` requires the value's class to be the expected class or a subclass of it. The value was a VmValue whose class did not conform. Error 675 is the cached `@Specialization` path; the same message also appears on the re-evaluation and fallback paths (676/677).

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java:798

    @Override
    public VmList getTypeArgumentMirrors() {
      // `Collection<X>` is represented by `CollectionTypeNode`,
      // but `Collection` is represented by `NonFinalClassTypeNode`
      return createUnknownTypeArgumentMirrors(clazz);
    }

    @ExplodeLoop
    @SuppressWarnings("unused")
    @Specialization(guards = "value.getVmClass() == cachedClass")
    protected Object eval(
        VmValue value,
        @Cached("value.getVmClass()") VmClass cachedClass,
        @Cached("clazz.isSuperclassOf(cachedClass)") boolean isSuperclass) {

      if (isSuperclass) return value;

      throw typeMismatch(value, clazz);
    }

    @Specialization
    protected Object eval(VmValue value) {
      if (clazz.isSuperclassOf(value.getVmClass())) return value;

      throw typeMismatch(value, clazz);
    }

    @Fallback
    protected Object eval(Object value) {
      throw typeMismatch(value, clazz);
    }

    @Override
    public @Nullable Object createDefaultValue(
        VirtualFrame frame,
        VmLanguage language,

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Make the value's class extend the expected class (`class Foo extends Expected`) or construct it with `new Expected { ... }`.
2. Loosen the declared type to a common superclass or union if subtypes vary.
3. Verify the imported module/version provides a class compatible with the expected one.
4. Check `value is ExpectedClass` before assignment during debugging.

Example fix

// before
 animal: Animal = new Dynamic {}
// after
 animal: Animal = new Dog {}   // class Dog extends Animal

// Pkl
if (value is ExpectedClass) {
  slot: ExpectedClass = value
}

function isExpected(value: Any): Boolean = value is ExpectedClass

// Guard with `is ExpectedClass` before assignment; embedders: catch PklException with 'not an instance of expected superclass'.

When it happens

Trigger: Assigning an object whose class is unrelated to (or a superclass of) the declared class type; passing a base-class instance where a subclass is required; feeding a Dynamic/List/etc. into a slot typed with a user-defined class.

Common situations: Class hierarchy changes after refactoring (property declared with an old class), importing a module whose class does not extend the expected one, or constructing `new Dynamic {}` where a typed class is expected.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• cannotApplyConstModifier
• type mismatch: value does not conform to declared type (clas
• type mismatch: value's class is not a subclass of expected c
• type mismatch: value is not the expected string literal
• type mismatch: value is not of type Typed

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