{"record":{"id":"ea2717386c12f93c","repo":"apple/pkl","slug":"type-mismatch-value-is-not-an-instance-of-expecte","errorCode":null,"errorMessage":"type mismatch: value is not an instance of expected superclass","messagePattern":"type mismatch: value is not an instance of expected superclass","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":798,"sourceCode":"\n    @Override\n    public VmList getTypeArgumentMirrors() {\n      // `Collection<X>` is represented by `CollectionTypeNode`,\n      // but `Collection` is represented by `NonFinalClassTypeNode`\n      return createUnknownTypeArgumentMirrors(clazz);\n    }\n\n    @ExplodeLoop\n    @SuppressWarnings(\"unused\")\n    @Specialization(guards = \"value.getVmClass() == cachedClass\")\n    protected Object eval(\n        VmValue value,\n        @Cached(\"value.getVmClass()\") VmClass cachedClass,\n        @Cached(\"clazz.isSuperclassOf(cachedClass)\") boolean isSuperclass) {\n\n      if (isSuperclass) return value;\n\n      throw typeMismatch(value, clazz);\n    }\n\n    @Specialization\n    protected Object eval(VmValue value) {\n      if (clazz.isSuperclassOf(value.getVmClass())) return value;\n\n      throw typeMismatch(value, clazz);\n    }\n\n    @Fallback\n    protected Object eval(Object value) {\n      throw typeMismatch(value, clazz);\n    }\n\n    @Override\n    public @Nullable Object createDefaultValue(\n        VirtualFrame frame,\n        VmLanguage language,","sourceCodeStart":780,"sourceCodeEnd":816,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L780-L816","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make the value's class extend the expected class (`class Foo extends Expected`) or construct it with `new Expected { ... }`.","Loosen the declared type to a common superclass or union if subtypes vary.","Verify the imported module/version provides a class compatible with the expected one.","Check `value is ExpectedClass` before assignment during debugging."],"exampleFix":"// before\n animal: Animal = new Dynamic {}\n// after\n animal: Animal = new Dog {}   // class Dog extends Animal","handlingStrategy":"type-guard","validationCode":"// Pkl\nif (value is ExpectedClass) {\n  slot: ExpectedClass = value\n}","typeGuard":"function isExpected(value: Any): Boolean = value is ExpectedClass","tryCatchPattern":"// Guard with `is ExpectedClass` before assignment; embedders: catch PklException with 'not an instance of expected superclass'.","preventionTips":["Keep class hierarchies in sync with declared property types","Run type-checking tests after refactoring `extends` relationships","Use shared superclasses or unions for polymorphic slots"],"tags":["pkl","type-mismatch","inheritance","typecheck"],"backgroundTag":"type-mismatch","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}