What causes "type mismatch: value is not of type Mapping" in apple/pkl?

Use Mapping entry syntax: `opts { ["a"] = "b" }` or `new Mapping { ... }`.

apple/pkl · error · VmTypeMismatchException

type mismatch: value is not of type Mapping

Error message

type mismatch: value is not of type Mapping

What it means

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.

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.

Example fix

// before
labels: Mapping<String> = Map("env", "prod")
// after
labels: Mapping<String> {
  ["env"] = "prod"
}

Defensive patterns

Strategy: type-guard

Validate before calling

assert(opts is Mapping<String>, "Mapping<V> requires entry syntax, not Map(...)")

Type guard

opts: Mapping<String> = if (opts is Mapping<String>) opts else new Mapping {}

Prevention

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.

When it happens

Trigger: 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" }`.

Common situations: 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).

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/3fb2e358c6d091a2. Report an issue: GitHub.

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java:1688

      }
      return consumer.accept(this);
    }
  }

  public static final class MappingTypeNode extends ListingOrMappingTypeNode {
    public MappingTypeNode(
        SourceSection sourceSection,
        VmLanguage language,
        TypeNode keyTypeNode,
        TypeNode valueTypeNode) {

      super(sourceSection, language, keyTypeNode, valueTypeNode);
    }

    @Override
    protected Object executeLazily(VirtualFrame frame, Object value) {
      if (!(value instanceof VmMapping vmMapping)) {
        throw typeMismatch(value, BaseModule.getMappingClass());
      }
      // execute type checks on mapping keys
      doEagerCheck(frame, vmMapping, false, true);
      if (vmMapping.isValueTypeKnownSubtypeOf(valueTypeNode)) {
        return vmMapping;
      }
      return new VmMapping(
          vmMapping.getEnclosingFrame(),
          vmMapping,
          EconomicMaps.emptyMap(),
          getValueTypeCastNode(),
          VmUtils.getReceiver(frame),
          VmUtils.getOwner(frame));
    }

    @Override
    public Object executeEagerly(VirtualFrame frame, Object value) {
      if (!(value instanceof VmMapping vmMapping)) {

View on GitHub (pinned to f3efcbfc9b)