apple/pkl · error · VmTypeMismatchException

type mismatch: value's class is not a subclass of expected c

Error message

type mismatch: value's class is not a subclass of expected class

What it means

This is a Pkl type-check failure from the module/this (`module` or open-class self) type check. The VM checks that the assigned value is a VmTyped object whose class is a subclass of the module/this class (NonFinalSelfTypeNode.executeLazily). Because the class is derived at runtime from the target object, this typically fires when a value that is not a module or class instance is used where the module/this type is expected, or a class-conformance rule is violated.

Source

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

          PType.MODULE,
          MirrorFactories.moduleTypeFactory);
    }

    public static NonFinalSelfTypeNode thisType(SourceSection sourceSection, VmClass clazz) {
      return new NonFinalSelfTypeNode(
          sourceSection, clazz, new GetReceiverNode(), PType.THIS, MirrorFactories.thisTypeFactory);
    }

    @Override
    protected Object executeLazily(VirtualFrame frame, Object value) {
      var clazz = ((VmObjectLike) getTargetNode.executeGeneric(frame)).getVmClass();

      if (value instanceof VmTyped typed) {
        var valueClass = typed.getVmClass();
        if (clazz.isSuperclassOf(valueClass)) return value;
      }

      throw typeMismatch(value, clazz);
    }

    @Override
    public VmTyped getMirror() {
      return mirrorFactory.create(null);
    }

    @Override
    public boolean doIsEquivalentTo(TypeNode other) {
      if (!(other instanceof NonFinalSelfTypeNode nonFinalSelfTypeNode)) {
        return false;
      }
      return clazz.equals(nonFinalSelfTypeNode.clazz);
    }

    @Override
    protected PType doExport() {
      return pType;

View on GitHub (pinned to f3efcbfc9b)

Solutions

Check the value being assigned at the reported source location; ensure it is an instance of the module/class the type expects (e.g. use `new Foo { ... }` or the correct module reference).
If you meant a plain object, change the declared type to `Dynamic` or the appropriate class instead of the module/this type.
Inspect `is` tests in Pkl: `value is ModuleClass` before assigning, or cast explicitly.
If it comes from a third-party library, update to a version where the API contract matches your usage.

Example fix

// before
foo: ModuleType = "not a module"
// after
foo: ModuleType = (new ModuleType {})  // or a module instance conforming to ModuleType

Defensive patterns

Strategy: type-guard

Validate before calling

// Pkl
if (value is ModuleType) {
  foo: ModuleType = value
} else {
  throw("value does not conform to ModuleType")
}

Type guard

function isModuleType(value: Any): Boolean = value is ModuleType

Try / catch

// Pkl errors abort evaluation; validate before assignment rather than catching.
// In Java embedders: catch org.pkl.core.PklException and inspect message for "type mismatch".

Prevention

Prefer `is` checks at boundaries before assigning to module/this-typed slots
Keep module type constraints on properties that only ever receive module instances
Run `pkl test` fixtures covering each assignment path

When it happens

Trigger: Assigning or passing a value (e.g. a Dynamic, List, String, or Int) into a slot/argument whose declared type is the enclosing module type, an open class `this` type, or a non-final self type; evaluating the type assertion in TypeNode.executeLazily when the value's runtime class is not a subclass of the computed target class.

Common situations: Confusing a module with its name (importing and assigning the module object vs. a property), applying `this`-typed constraints to values of other classes, amending/writing properties on an object where the module type constraint is enforced, or a typechecked Pkl library API receiving a non-module receiver.

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

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