apple/pkl · error · VmTypeMismatchException

type constraint violation: value does not fit in Int8

Error message

type constraint violation: value does not fit in Int8

What it means

Pkl throws this when a value being checked against the Int8 type alias is a Long (Pkl's integer representation) whose magnitude exceeds the signed 8-bit range (-128..127). executeLazily accepts the value only if l == l.byteValue(); otherwise it raises a type-constraint violation anchored at the Int8 alias's constraint source section. It is Pkl's way of enforcing narrowing integer subtypes.

Source

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

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

  public static final class Int8TypeAliasTypeNode extends IntSlotTypeNode {
    public Int8TypeAliasTypeNode() {
      super(VmUtils.unavailableSourceSection());
    }

    @Override
    protected Object executeLazily(VirtualFrame frame, Object value) {
      if (value instanceof Long l) {
        if (l == l.byteValue()) return value;

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

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

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

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

    @Override
    public VmTyped getMirror() {

View on GitHub (pinned to f3efcbfc9b)

Solutions

Change the declared type to Int (or Int16/Int32) so the value's range fits
Clamp or compute the value to stay within -128..127 (e.g. use `.toInt8()` after range validation)
If the value is not an integer at all, fix the source value to be an integer
Use `is Int8` in a conditional to branch instead of forcing the cast

Example fix

// before
retries: Int8 = 300
// after
retries: Int = 300
// or keep Int8 with a valid value
retries: Int8 = 12

Defensive patterns

Strategy: validation

Validate before calling

function fitsInt8(v) { return Number.isInteger(v) && v >= -128 && v <= 127; }
// pkl-side: assert(value is Int8, "value must fit Int8")

Type guard

function isInt8(v) { return typeof v === 'number' && Number.isInteger(v) && v >= -128 && v <= 127; }

Prevention

Default to Int unless you specifically need bounded semantics
Compute ranges before assigning to narrow integer types
Use `value is Int8` assertions in amends blocks

When it happens

Trigger: A property or expression is typed Int8 (e.g. `x: Int8`) and is assigned a literal or computed Long outside -128..127, or a non-Long value (e.g. Float or String) reaches the Int8 check, producing the nested VmTypeMismatchException.Simple against Int.

Common situations: Copying a port/age/quantity value from another config that was a plain Int; arithmetic like `256 * multiplier` that overflows the Int8 range; JSON/YAML import carrying 300 where Int8 is declared.

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/f0746b1fe8ce6c61. Report an issue: GitHub.