apple/pkl · error · VmTypeMismatchException.Constraint

type mismatch

Error message

type mismatch

What it means

TypeNode.constraintException builds the generic "type mismatch" VmTypeMismatchException.Constraint used when a value does not conform to a (structural) type node — e.g. a collection element, map value, or type-argument position where the node knows the value was rejected but has no richer per-node data. It records a SyntheticNode over the source section with the failing result.

Source

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

  public final boolean isSelfType() {
    var ret = new MutableBoolean(false);
    acceptTypeNode(
        true,
        typeNode -> {
          if (typeNode instanceof NonFinalSelfTypeNode || typeNode instanceof FinalSelfTypeNode) {
            ret.set(true);
            return false;
          }
          return true;
        });
    return ret.get();
  }

  /** Visit child type nodes of this type. */
  protected abstract boolean acceptTypeNode(boolean visitTypeArguments, TypeNodeConsumer consumer);

  protected VmTypeMismatchException constraintException(Object value, SourceSection sourceSection) {
    throw new VmTypeMismatchException.Constraint(
        sourceSection,
        value,
        sourceSection,
        Map.of(new SyntheticNode(sourceSection), List.of(false)));
  }

  public static TypeNode forClass(SourceSection sourceSection, VmClass clazz) {
    return clazz.isClosed()
        ? new FinalClassTypeNode(sourceSection, clazz)
        : TypeNodeFactory.NonFinalClassTypeNodeGen.create(sourceSection, clazz);
  }

  public static PType export(@Nullable TypeNode node) {
    return node != null ? node.doExport() : PType.UNKNOWN;
  }

  public static VmTyped getMirror(@Nullable TypeNode node) {
    return node != null ? node.getMirror() : MirrorFactories.unknownTypeFactory.create(null);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Locate the source section in the error to find which type position rejected the value.
2. Validate each element/property of collections against the declared element/property types before assignment.
3. Fix the offending value or widen the declared type if it is unnecessarily strict.
4. Use `pkl test` or a REPL to check values against the type incrementally.

Example fix

// before (Pkl)
ports: List<Int> = List(80, "443")
// after
ports: List<Int> = List(80, 443)

// Pkl: validate collection elements against the element type
ports.map((p) -> if (p is Int) p else error("non-Int port: ${p}"))

When it happens

Trigger: A value fails to match a parameterized/structural type node (List<Int> receiving a list containing strings, a typed object property receiving the wrong shape, etc.), and the node raises the standard constraint exception.

Common situations: Feed-forward configs where an element of a listing/mapping violates its declared element type; API-facing modules validating external JSON/YAML data converted into Pkl values.

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

• Error converting property `%s` in Pkl object of type `%s` to
• The top-level value of a YAML stream must have type `Collect
• type constraint mismatch
• type mismatch (Nothing type)
• union type mismatch

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