apple/pkl · error · VmTypeMismatchException

type constraint violation: Int value out of range for this t

Error message

type constraint violation: Int value out of range for this type alias

What it means

Thrown by an Int-range-constrained type alias check: a Long value is outside the bit-range the alias allows (checked with a bit mask), so the constraint section reports an out-of-range type constraint violation. Non-Long values instead raise a simple Int type mismatch.

Source

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

  protected abstract static class IntMaskSlotTypeNode extends IntSlotTypeNode {
    protected final long mask;

    IntMaskSlotTypeNode(long mask) {
      super(VmUtils.unavailableSourceSection());
      this.mask = mask;
    }

    @Override
    protected final Object executeLazily(VirtualFrame frame, Object value) {
      var typealias = getVmTypeAlias();
      assert typealias != null;
      if (value instanceof Long l) {
        if ((l & mask) == l) return value;

        CompilerDirectives.transferToInterpreterAndInvalidate();
        var sourceSection = typealias.getConstraintSection();
        throw constraintException(value, sourceSection);
      }

      throw new VmTypeMismatchException.Simple(
          typealias.getBaseTypeSection(), value, BaseModule.getIntClass());
    }

    @Override
    public final VmClass getVmClass() {
      return BaseModule.getIntClass();
    }

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

    @Override
    public final boolean doIsEquivalentTo(TypeNode other) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

Clamp or change the value to fit the alias's allowed range (verify the alias's constraint, e.g. 0..255 for UInt8).
Widen the annotation to a larger Int alias (e.g. Int16/Int32) if larger values are legitimate.
Check for sign errors where negative values hit unsigned aliases.
Validate numeric config inputs against the expected range at the source.

Example fix

// before
b: UInt8 = 300

// after
b: UInt8 = 255 // or change type to Int16 for values > 255

Defensive patterns

Strategy: validation

Validate before calling

function inRange(v: Int, min: Int, max: Int): Boolean = v >= min && v <= max // e.g. UInt8: 0..255

Type guard

function isUInt8(v: Int): Boolean = v is Int && v >= 0 && v <= 255

Prevention

Check each Int alias's constraint range before assigning.
Clamp or widen types for values near range boundaries.
Watch for negatives assigned to unsigned aliases.
Validate numeric inputs at config authoring time.

When it happens

Trigger: A value assigned to an Int subtype alias (e.g. Int8/Int16/UInt8-style constrained aliases, or user aliases with `c` constraint ranges) exceeds the representable range — e.g. 300 for UInt8, or a negative number for an unsigned alias.

Common situations: Port numbers, byte values, or enum-like numeric constants exceeding the alias range; converting from wider integers in codegen; config values copied from examples with larger ranges.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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