{"record":{"id":"e1acb762430b89e6","repo":"apple/pkl","slug":"vmtypemismatchexception-reference-referent-type-i","errorCode":null,"errorMessage":"VmTypeMismatchException.Reference (referent type is not a subtype)","messagePattern":"VmTypeMismatchException\\.Reference \\(referent type is not a subtype\\)","errorType":"exception","errorClass":"VmTypeMismatchException.Reference","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":2251,"sourceCode":"      // So `this` can only correspond to the receiver where the type check/annotation is written.\n      var thisClass = ((VmClass) getReceiverClassNode.executeGeneric(frame));\n\n      // NB: This will be wrong for deprecated usage of the `module` type in typealias bodies.\n      // It will always resolve to the module where the type check/annotation is written\n      // not the type itself. This is no _more_ broken than it was before.\n      var moduleClass = VmUtils.getClass(getModuleNode.executeGeneric(frame));\n\n      return doEval(value, thisClass, moduleClass);\n    }\n\n    @TruffleBoundary\n    private Object doEval(VmReference value, VmClass thisClass, VmClass moduleClass) {\n      var referentType = referentTypeNode.doExport();\n      if (value.referentTypeIsSubtypeOf(referentType, thisClass.export(), moduleClass.export())) {\n        return value;\n      }\n\n      throw new VmTypeMismatchException.Reference(\n          sourceSection, value, domainTypeNode.doExport(), referentType);\n    }\n\n    @Fallback\n    protected Object fallback(Object value) {\n      throw typeMismatch(value, RefModule.getReferenceClass());\n    }\n\n    @Override\n    protected boolean acceptTypeNode(boolean visitTypeArguments, TypeNodeConsumer consumer) {\n      if (visitTypeArguments)\n        return consumer.accept(this)\n            && consumer.accept(domainTypeNode)\n            && consumer.accept(referentTypeNode);\n      return consumer.accept(this);\n    }\n\n    @Override","sourceCodeStart":2233,"sourceCodeEnd":2269,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L2233-L2269","documentation":"In ReferenceTypeNode.doEval, after the domain check passes, Pkl verifies the reference's referent type via value.referentTypeIsSubtypeOf(...). If the referent type is not a subtype of the declared referent type, it throws VmTypeMismatchException.Reference indicating the reference points at a value of an incompatible type.","triggerScenarios":"A `Reference<T>` (or TypeAlias/constrained reference) is checked where the actual referent's class is not a subtype of T; doEval compares referentTypeNode.doExport() against the value's referent type using thisClass/moduleClass context and throws on failure.","commonSituations":"Storing a reference to an object of the wrong class; changing a property's declared referent type to a narrower class while existing references still point at the broader type; typealias constraints over references after upstream type changes.","solutions":["Make the referenced value an instance of (a subtype of) the declared referent type.","Widen the declared referent type parameter to a common supertype of the actual referents.","Check the exported referent type in the message to see exactly which type was expected."],"exampleFix":"// before\nbase: Reference<Base> = derived  // derived: Derived, not a subtype of Base\n// after\nabstract class Base\nclass Derived extends Base\nbase: Reference<Base> = derived","handlingStrategy":"type-guard","validationCode":"// Pkl: verify referent type before assigning\nfunction checkReferent(r: Reference): Boolean = r.referent is ExpectedType","typeGuard":"value is Reference<ExpectedType>","tryCatchPattern":null,"preventionTips":["Ensure referenced objects derive from the declared referent class.","When narrowing a referent type, update all producers of the reference.","Use `is` type tests on the referent before constructing the reference."],"tags":["pkl","type-mismatch","reference-type"],"backgroundTag":"type-mismatch","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}