{"record":{"id":"3fb2e358c6d091a2","repo":"apple/pkl","slug":"type-mismatch-value-is-not-of-type-mapping","errorCode":null,"errorMessage":"type mismatch: value is not of type Mapping","messagePattern":"type mismatch: value is not of type Mapping","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":1688,"sourceCode":"      }\n      return consumer.accept(this);\n    }\n  }\n\n  public static final class MappingTypeNode extends ListingOrMappingTypeNode {\n    public MappingTypeNode(\n        SourceSection sourceSection,\n        VmLanguage language,\n        TypeNode keyTypeNode,\n        TypeNode valueTypeNode) {\n\n      super(sourceSection, language, keyTypeNode, valueTypeNode);\n    }\n\n    @Override\n    protected Object executeLazily(VirtualFrame frame, Object value) {\n      if (!(value instanceof VmMapping vmMapping)) {\n        throw typeMismatch(value, BaseModule.getMappingClass());\n      }\n      // execute type checks on mapping keys\n      doEagerCheck(frame, vmMapping, false, true);\n      if (vmMapping.isValueTypeKnownSubtypeOf(valueTypeNode)) {\n        return vmMapping;\n      }\n      return new VmMapping(\n          vmMapping.getEnclosingFrame(),\n          vmMapping,\n          EconomicMaps.emptyMap(),\n          getValueTypeCastNode(),\n          VmUtils.getReceiver(frame),\n          VmUtils.getOwner(frame));\n    }\n\n    @Override\n    public Object executeEagerly(VirtualFrame frame, Object value) {\n      if (!(value instanceof VmMapping vmMapping)) {","sourceCodeStart":1670,"sourceCodeEnd":1706,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L1670-L1706","documentation":"Thrown by the Mapping type-check node's executeLazily when the checked value is not a VmMapping. `Mapping<V>` is Pkl's object-based key/value collection (`new Mapping { [\"k\"] = ... }`); plain Maps, Lists, or other values fail the instanceof check and produce typeMismatch naming the `Mapping` class. Key checks then run eagerly before the value-type check.","triggerScenarios":"A `Mapping<V>` constraint receives a non-Mapping value, e.g. `opts: Mapping<String> = Map(\"a\", \"b\")` (a VmMap) instead of `new Mapping { [\"a\"] = \"b\" }`.","commonSituations":"Assigning a `Map(...)` literal or JSON object to a Mapping-typed property; using `= { ... }` assignment syntax where member/entry syntax is required; confusing Map vs Mapping (the two are distinct Pkl types).","solutions":["Use Mapping entry syntax: `opts { [\"a\"] = \"b\" }` or `new Mapping { ... }`.","Change the declared type to `Map<String, V>` if a plain Map literal is what you produce.","Convert a Map into a Mapping by spreading entries in a new Mapping when necessary.","Confirm external data bindings: JSON objects map naturally to Mapping, but only when built as one."],"exampleFix":"// before\nlabels: Mapping<String> = Map(\"env\", \"prod\")\n// after\nlabels: Mapping<String> {\n  [\"env\"] = \"prod\"\n}","handlingStrategy":"type-guard","validationCode":"assert(opts is Mapping<String>, \"Mapping<V> requires entry syntax, not Map(...)\")","typeGuard":"opts: Mapping<String> = if (opts is Mapping<String>) opts else new Mapping {}","tryCatchPattern":null,"preventionTips":["Use `[\"key\"] = value` entry syntax for Mapping-typed properties.","Never assign `Map(...)` literals to Mapping-typed properties.","Document the Map vs Mapping distinction in team style guides."],"tags":["pkl","typecheck","mapping","type-mismatch"],"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"}