{"record":{"id":"04d1615a88074530","repo":"apple/pkl","slug":"type-mismatch-value-does-not-conform-to-declared","errorCode":null,"errorMessage":"type mismatch: value does not conform to declared type (class)","messagePattern":"type mismatch: value does not conform to declared type \\(class\\)","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":461,"sourceCode":"      this.pType = pType;\n      this.mirrorFactory = mirrorFactory;\n    }\n\n    public static FinalSelfTypeNode moduleType(SourceSection sourceSection, VmClass clazz) {\n      return new FinalSelfTypeNode(\n          sourceSection, clazz, PType.MODULE, MirrorFactories.moduleTypeFactory);\n    }\n\n    public static FinalSelfTypeNode thisType(SourceSection sourceSection, VmClass clazz) {\n      return new FinalSelfTypeNode(\n          sourceSection, clazz, PType.THIS, MirrorFactories.thisTypeFactory);\n    }\n\n    @Override\n    protected Object executeLazily(VirtualFrame frame, Object value) {\n      if (VmUtils.getClass(value) == clazz) return value;\n\n      throw typeMismatch(value, clazz);\n    }\n\n    @Override\n    public VmTyped getMirror() {\n      return mirrorFactory.create(null);\n    }\n\n    @Override\n    public boolean doIsEquivalentTo(TypeNode other) {\n      if (!(other instanceof FinalSelfTypeNode finalSelfTypeNode)) {\n        return false;\n      }\n      return clazz.equals(finalSelfTypeNode.clazz);\n    }\n\n    @Override\n    protected PType doExport() {\n      return pType;","sourceCodeStart":443,"sourceCodeEnd":479,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L443-L479","documentation":"TypeNode.executeLazily checks that a value assigned to a property with a declared class type actually is an instance of that exact class (`VmUtils.getClass(value) == clazz`). If not, it throws a type mismatch stating the value does not conform to the declared type. This enforces Pkl's type annotations on property values.","triggerScenarios":"Assigning an object of a different (possibly related but not identical) class to a property typed as a specific class; amending a class where the type check expects the exact class; passing a subtype where only the exact class passes this fast path.","commonSituations":"Confusing similarly named classes; assigning a String where a Number-typed property exists; supplying an untyped dynamic object to a typed property in amends/new expressions.","solutions":["Assign a value of the exact declared class (create it with the right class)","Check for typos or wrong imports producing a different class","Use a typeconversion or adjust the declared type to a common supertype if intentional"],"exampleFix":"// before\nserver: Server { ... }  // but value is an Endpoint instance\n// after\nserver: Endpoint { ... }  // or construct a Server","handlingStrategy":"type-guard","validationCode":"// verify the class of the value matches declared type before assignment\nif (value.constructor !== DeclaredClass) throw new Error(\"value does not conform to declared type\");","typeGuard":"function isExactInstance(v, clazz){ return v != null && Object.getPrototypeOf(v).constructor === clazz; }","tryCatchPattern":"try { assign(prop, value); } catch (e) { if (String(e).includes(\"does not conform\")) { /* correct value class and retry */ } else { throw e; } }","preventionTips":["Match value class to the property's declared class exactly","Watch for typos and wrong imports yielding a different class"],"tags":["pkl","type-mismatch","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-14T16:17:12.679Z"}