{"record":{"id":"ec748ed862bb131b","repo":"apple/pkl","slug":"type-mismatch-value-is-not-of-type-reference","errorCode":null,"errorMessage":"type mismatch: value is not of type Reference","messagePattern":"type mismatch: value is not of type Reference","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":2257,"sourceCode":"      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\n    public VmClass getVmClass() {\n      return RefModule.getReferenceClass();\n    }\n\n    @Override\n    public VmList getTypeArgumentMirrors() {","sourceCodeStart":2239,"sourceCodeEnd":2275,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L2239-L2275","documentation":"Thrown by the @Fallback path of the Reference class type check (Ref module). The value failed an `is Reference` check used by `Ref`-typed annotations (e.g. typed object references like `Ref<Map>` or `Ref<Listing>`).","triggerScenarios":"A value is checked against a `Ref<...>` type annotation but the value is not a Reference — e.g. an Int, String, null, or a plain object where `Ref<T>` requires a reference to a T.","commonSituations":"Using Ref-module APIs or `Ref<T>` annotations and passing the contained value directly instead of a reference; passing a concrete value (like a string) where a reference to a typed object is expected.","solutions":["Supply a Reference value (e.g. from `Ref` combinators or a reference-typed property) rather than a raw value.","If you have the underlying value, wrap or reference it per the Ref module API instead of passing it directly.","Remove an unintended `Ref<T>` annotation if a plain `T` was intended.","Check that null is not sneaking into a Ref-typed slot."],"exampleFix":"// before\nr: Ref<Mapping> = new Mapping {}\n\n// after\nr: Ref<Mapping> = someRef // a value of type Ref<Mapping>","handlingStrategy":"type-guard","validationCode":"if (value is Reference) { /* ok */ } else { /* wrap or fix */ }","typeGuard":"function isReference(v: Any): Boolean = v is Reference","tryCatchPattern":null,"preventionTips":["Don't pass raw values into Ref<T> slots; use reference-typed sources.","Avoid nullable values in Ref positions.","Keep Ref annotations only where references are genuinely produced."],"tags":["pkl","type-mismatch","ref-module"],"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"}