apple/pkl · error · VmTypeMismatchException

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

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.

Solutions

1. Clamp or change the value to fit the alias's allowed range (verify the alias's constraint, e.g. 0..255 for UInt8).
2. Widen the annotation to a larger Int alias (e.g. Int16/Int32) if larger values are legitimate.
3. Check for sign errors where negative values hit unsigned aliases.
4. 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

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

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

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

• Cannot convert pkl.base#Int
• Cannot convert pkl.base#Int
• Cannot convert pkl.base#Int
• cannotConvertLargeFloat|cannotConvertNonFiniteFloat…
• notASubclassOfTyped

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

Appendix: 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)