{"record":{"id":"f0746b1fe8ce6c61","repo":"apple/pkl","slug":"type-constraint-violation-value-does-not-fit-in-i","errorCode":null,"errorMessage":"type constraint violation: value does not fit in Int8","messagePattern":"type constraint violation: value does not fit in Int8","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":2612,"sourceCode":"    @Override\n    public VmTypeAlias getVmTypeAlias() {\n      return BaseModule.getUInt8TypeAlias();\n    }\n  }\n\n  public static final class Int8TypeAliasTypeNode extends IntSlotTypeNode {\n    public Int8TypeAliasTypeNode() {\n      super(VmUtils.unavailableSourceSection());\n    }\n\n    @Override\n    protected Object executeLazily(VirtualFrame frame, Object value) {\n      if (value instanceof Long l) {\n        if (l == l.byteValue()) return value;\n\n        CompilerDirectives.transferToInterpreterAndInvalidate();\n        var sourceSection = BaseModule.getInt8TypeAlias().getConstraintSection();\n        throw constraintException(value, sourceSection);\n      }\n\n      throw new VmTypeMismatchException.Simple(\n          BaseModule.getInt8TypeAlias().getBaseTypeSection(), value, BaseModule.getIntClass());\n    }\n\n    @Override\n    public VmClass getVmClass() {\n      return BaseModule.getIntClass();\n    }\n\n    @Override\n    public VmTypeAlias getVmTypeAlias() {\n      return BaseModule.getInt8TypeAlias();\n    }\n\n    @Override\n    public VmTyped getMirror() {","sourceCodeStart":2594,"sourceCodeEnd":2630,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L2594-L2630","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nretries: Int8 = 300\n// after\nretries: Int = 300\n// or keep Int8 with a valid value\nretries: Int8 = 12","handlingStrategy":"validation","validationCode":"function fitsInt8(v) { return Number.isInteger(v) && v >= -128 && v <= 127; }\n// pkl-side: assert(value is Int8, \"value must fit Int8\")","typeGuard":"function isInt8(v) { return typeof v === 'number' && Number.isInteger(v) && v >= -128 && v <= 127; }","tryCatchPattern":null,"preventionTips":["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"],"tags":["pkl","integer-range","type-constraint"],"backgroundTag":"value-out-of-range","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}