apple/pkl · error · VmTypeMismatchException

type constraint violation: value must not be null (non-null

Error message

type constraint violation: value must not be null (non-null type alias)

What it means

NonNullTypeAliasTypeNode.executeLazily: a value checked against a non-null type alias is null (VmNull), violating the alias's nullability constraint, so a type-constraint violation is thrown. The input at fault is a null value flowing into a position typed by a non-null type alias (e.g. `x: NonNull<Int?>`-style alias).

Source

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

      return new PType.TypeVariable(typeParameter);
    }

    @Override
    protected boolean acceptTypeNode(boolean visitTypeArguments, TypeNodeConsumer consumer) {
      return consumer.accept(this);
    }
  }

  public static final class NonNullTypeAliasTypeNode extends WriteFrameSlotTypeNode {
    public NonNullTypeAliasTypeNode() {
      super(VmUtils.unavailableSourceSection());
    }

    @Override
    protected Object executeLazily(VirtualFrame frame, Object value) {
      if (value instanceof VmNull) {
        CompilerDirectives.transferToInterpreterAndInvalidate();
        throw constraintException(value, BaseModule.getNonNullTypeAlias().getConstraintSection());
      }
      return value;
    }

    @Override
    public VmTypeAlias getVmTypeAlias() {
      return BaseModule.getNonNullTypeAlias();
    }

    @Override
    public VmTyped getMirror() {
      return MirrorFactories.typeAliasTypeFactory.create(this);
    }

    @Override
    public boolean doIsEquivalentTo(TypeNode other) {
      return other instanceof NonNullTypeAliasTypeNode;
    }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Ensure the value is non-null before assigning it to the non-null-aliased property.
2. Relax the type alias (drop the non-null constraint) if null is legitimate.

Example fix

// before
x: NonNull<Int> = maybeValue // maybeValue may be null

// after
x: NonNull<Int> = maybeValue ?? 0

if (value != null) { /* safe to bind to NonNull alias */ }

function nonNull<T>(v: T?): Boolean = v != null

When it happens

Trigger: A property or expression typed with the non-null type alias (`x: NonNull<T>` or via a user non-null alias) receives null at runtime during lazy evaluation.

Common situations: Defaults that resolve to null; chained lookups returning null (`foo?.bar` where foo is null); optional bindings that were expected to be non-null but a parent object omitted them.

Related errors

• type constraint mismatch
• type mismatch: type constraint must be a Boolean or a Functi
• type constraint violation: Int value out of range for this t
• type constraint violation: value does not fit in Int8
• type constraint violation: value does not fit in Int16

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