{"record":{"id":"39e01501727e4b3d","repo":"hibernate/hibernate-orm","slug":"cannot-coerce-integer-value-s-to-byte-overflo","errorCode":null,"errorMessage":"Cannot coerce Integer value `%s` to Byte : overflow","messagePattern":"Cannot coerce Integer value `(.+?)` to Byte : overflow","errorType":"exception","errorClass":"CoercionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java","lineNumber":48,"sourceCode":"\t\t\t);\n\t\t}\n\n\t\tif ( value < Byte.MIN_VALUE ) {\n\t\t\tthrow new CoercionException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\"Cannot coerce Short value `%s` to Byte : underflow\",\n\t\t\t\t\t\t\tvalue\n\t\t\t\t\t)\n\t\t\t);\n\t\t}\n\n\t\treturn value.byteValue();\n\t}\n\n\tpublic static Byte toByte(Integer value) {\n\t\tif ( value > Byte.MAX_VALUE ) {\n\t\t\tthrow new CoercionException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\"Cannot coerce Integer value `%s` to Byte : overflow\",\n\t\t\t\t\t\t\tvalue\n\t\t\t\t\t)\n\t\t\t);\n\t\t}\n\n\t\tif ( value < Byte.MIN_VALUE ) {\n\t\t\tthrow new CoercionException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\"Cannot coerce Integer value `%s` to Byte : underflow\",\n\t\t\t\t\t\t\tvalue\n\t\t\t\t\t)\n\t\t\t);\n\t\t}\n","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java#L30-L66","documentation":"CoercionHelper.toByte(Integer) throws CoercionException('Cannot coerce Integer value ... overflow') when an Integer exceeds Byte.MAX_VALUE (127). Like the Short variant, it is a fail-fast guard on the narrowing conversion invoked from ByteJavaType.coerceOrNull when a byte attribute receives an Integer.","triggerScenarios":"Binding an int literal or Integer parameter above 127 (e.g., 200) to a byte attribute in HQL; int-typed query results coerced into byte fields; Criteria parameters typed Integer.","commonSituations":"Java code naturally producing int values bound to byte columns; schema drift from tinyint to int; UI inputs parsed as Integer and passed through unchecked.","solutions":["Widen the attribute and column to int (or short) if values exceed 127.","Range-check and clamp/reject Integer values before binding to the byte attribute.","Convert to Byte explicitly after validation."],"exampleFix":"// before\nint limit = 300;\nquery.setParameter(\"limit\", limit); // byte attribute -> CoercionException: overflow\n\n// after\n@Basic private int limit; // widened\n// or guard: if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) throw ...; query.setParameter(\"limit\", (byte) v);","handlingStrategy":"validation","validationCode":"static boolean fitsByte(int v) {\n    return v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE;\n}\n// before binding: if (!fitsByte(v)) throw new IllegalArgumentException(\"Value \" + v + \" out of byte range\");","typeGuard":"static Byte toByteOrNull(int v) {\n    return (v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE) ? (byte) v : null;\n}","tryCatchPattern":null,"preventionTips":["Cast int literals to byte only after a range check.","Keep HQL parameter types aligned with attribute types (byte param for byte field).","Widen byte columns/fields once real data starts approaching 127."],"tags":["hibernate","byte","coercion","overflow","narrowing"],"backgroundTag":"numeric-overflow-coercion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}