apple/pkl · error · VmTypeMismatchException.Constraint

type constraint mismatch

Error message

type constraint mismatch

What it means

A Pkl type constraint (a `is`/typecheck assertion on a property or type) failed while power assertions were enabled (vmContext.getPowerAssertionsEnabled() and not inside a tracker-less type test). After executing the constraint body with value tracking, the evaluator throws VmTypeMismatchException.Constraint, rendered as "type constraint mismatch", recording which intermediate values were produced during evaluation to explain the failure.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/type/TypeConstraintNode.java:69

  @Specialization
  protected void eval(VirtualFrame frame, boolean result) {
    initConstraintSlot(frame);

    if (!result) {
      CompilerDirectives.transferToInterpreterAndInvalidate();
      var vmContext = VmContext.get(this);
      var localContext = VmLanguage.get(this).localContext.get();
      // Use power assertions if enabled and not in type test or already instrumenting.
      // This prevents `is` checks from triggering instrumentation, but allows them to
      // participate if instrumentation is already active.
      var usePowerAssertions =
          vmContext.getPowerAssertionsEnabled()
              && (!localContext.isInTypeTest() || localContext.hasActiveTracker());
      if (usePowerAssertions) {
        try (var valueTracker = vmContext.getValueTrackerFactory().create()) {
          getBodyNode().executeGeneric(frame);
          throw new VmTypeMismatchException.Constraint(
              sourceSection,
              frame.getAuxiliarySlot(customThisSlot),
              sourceSection,
              valueTracker.values());
        }
      } else {
        throw new VmTypeMismatchException.Constraint(
            sourceSection, frame.getAuxiliarySlot(customThisSlot), sourceSection, null);
      }
    }
  }

  @Specialization
  protected void eval(
      VirtualFrame frame,
      VmFunction function,
      @Cached(value = "createApplyNode()", neverDefault = true) ApplyVmFunction1Node applyNode) {
    initConstraintSlot(frame);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Read the mismatch diagnostics: the tracked values show how the constraint evaluation failed (e.g. intermediate results of chained predicates).
2. Fix the supplied value so it satisfies the declared type constraint, or correct the constraint if it is wrong.
3. Temporarily disable power assertions if the richer diagnostics are unwanted, but prefer fixing the value/constraint.
4. Reproduce with a minimal snippet to confirm which constraint (property type vs. element type) rejects the value.

Example fix

// before (Pkl)
port: Int(this > 1024 && this < 65536) = 80 // fails: 80 <= 1024
// after
port: Int(this > 1024 && this < 65536) = 8080

// Pkl: validate before assignment
assert(cond(value), "value ${value} must satisfy the declared constraint")
x: ConstraintType = value

When it happens

Trigger: A value fails a property type constraint or `is` type test at runtime while power assertions are enabled; e.g. assigning a value that does not satisfy `x is Int(isEven)` or a listing element violating its declared element type constraint.

Common situations: Config values that don't satisfy declared constraints (wrong numeric ranges, malformed strings, wrong object shape); tests or REPL runs with power assertions enabled surfacing richer mismatch diagnostics than production.

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

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

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