{"record":{"id":"8e8a5dcdd824b0d4","repo":"apple/pkl","slug":"vmtypemismatchexception-reference-domain-type-che","errorCode":null,"errorMessage":"VmTypeMismatchException.Reference (domain type check failed for reference)","messagePattern":"VmTypeMismatchException\\.Reference \\(domain type check failed for reference\\)","errorType":"exception","errorClass":"VmTypeMismatchException.Reference","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":2228,"sourceCode":"      return violation.getOrNull();\n    }\n\n    @Override\n    protected final boolean isIncludedInTrace(Node node) {\n      return node instanceof ReferenceTypeNode || node instanceof ConstrainedTypeNode;\n    }\n\n    @Specialization\n    protected Object eval(VirtualFrame frame, VmReference value) {\n      if (domainTypeNode.isNoopTypeCheck() && referentTypeNode.isNoopTypeCheck()) {\n        return value;\n      }\n\n      try {\n        domainTypeNode.execute(frame, value.getDomain());\n      } catch (VmTypeMismatchException e) {\n        CompilerDirectives.transferToInterpreter();\n        throw new VmTypeMismatchException.Reference(\n            sourceSection, value, domainTypeNode.doExport(), referentTypeNode.doExport());\n      }\n\n      // NB: this is correct because the `this` type is not allowed in typealias bodies.\n      // 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();","sourceCodeStart":2210,"sourceCodeEnd":2246,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L2210-L2246","documentation":"When checking a `Reference<X>` (a Pkl Reference value), the node first validates the reference's domain by executing its domainTypeNode. If the domain check throws VmTypeMismatchException, the error is re-thrown as VmTypeMismatchException.Reference reporting that the reference's domain is incompatible with the expected domain/referent type.","triggerScenarios":"A value typed as `Reference<T>` (e.g. from pkl:base Reference or Resource/Module references) has a domain that fails its declared domain type check; the catch block at TypeNode.java:2228 converts it into VmTypeMismatchException.Reference with the exported domain and referent types.","commonSituations":"Working with cross-module or resource references where the referenced object's module/type does not conform to the declared reference type; refactoring module hierarchies so a previously valid reference no longer satisfies its domain constraint.","solutions":["Inspect the reported domain type and make the referenced value's domain conform to it.","Update the Reference<...> type annotation to match the actual domain/referent of the value.","Verify the referenced module/import still exports the expected type after refactoring."],"exampleFix":"// before\nref: Reference<Module_A.Thing> = moduleB.thing\n// after\nref: Reference<Module_B.Thing> = moduleB.thing","handlingStrategy":"type-guard","validationCode":"// Pkl: check reference domain before use\nfunction checkRef(r: Reference, domain: Class): Boolean = r.domain.getClass().isSubclassOf(domain)","typeGuard":"value is Reference<ExpectedType>","tryCatchPattern":null,"preventionTips":["Keep Reference<...> annotations in sync with the modules you import.","After refactoring module hierarchies, re-run type checks on all referencing modules.","Prefer plain object references over Reference<T> unless domain checking is needed."],"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"}