{"record":{"id":"553c3e0437efad03","repo":"hibernate/hibernate-orm","slug":"cannot-coerce-long-value-s-to-byte-overflow","errorCode":null,"errorMessage":"Cannot coerce Long value `%s` to Byte : overflow","messagePattern":"Cannot coerce Long 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":72,"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 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\n\t\treturn value.byteValue();\n\t}\n\n\tpublic static Byte toByte(Long 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 Long 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 Long 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":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java#L54-L90","documentation":"Hibernate throws this CoercionException when a Long value must be narrowed to Byte (range -128..127) and it exceeds 127. It originates from CoercionHelper.toByte(Long), called by ByteJavaType.coerce when a Long-typed value is supplied for a Byte-mapped attribute. Hibernate 6 deliberately rejects lossy narrowing instead of truncating like a Java cast would; the message includes the offending value. This is a mapping/data contract problem, not a transient failure.","triggerScenarios":"A Byte/byte entity attribute receives a Long > 127: `entity.setFlag(someLongValue)` where the setter accepts Number/Object, or binding a long query parameter against a Byte-typed path (`setParameter(\"b\", 300L)`), or Session.merge of a detached graph whose Byte field actually holds a Long (e.g. deserialized from JSON with BigInteger/Long ids).","commonSituations":"Copy DTOs where JSON numbers deserialize as Long (Jackson with USE_LONG_FOR_INTS, or values above int range) onto Byte fields; reusing id-like Long counters for small code fields; Hibernate 5 -> 6 upgrades where oversized values previously truncated silently; MySQL unsigned TINYINT holding 128..255 read back as a wider integer then re-persisted into a Byte attribute.","solutions":["Align the attribute type with the value domain (Byte -> Long/Integer), or narrow explicitly after checking range (`longValue.byteValue()` only when -128..127).","Convert the source value to Long-correct type at the boundary: fix the DTO/deserializer so the field is a Byte/Integer, not Long.","Use an AttributeConverter<Long,Byte> if the narrowing is intentional, making the contract explicit.","Validate incoming longs against the byte range at the API/import boundary and reject oversized values early."],"exampleFix":"// before\nMap<String,Object> props = new HashMap<>();\nprops.put(\"code\", 999L);            // Long\nsession.persist(dynamicEntity);     // Byte-mapped 'code' -> CoercionException: overflow\n\n// after\nprops.put(\"code\", (byte) clampToByteRange(999L));\n// or change attribute/column from tinyint to a wider type","handlingStrategy":"validation","validationCode":"Long v = (Long) rawValue;\nif (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) throw new IllegalArgumentException(\"out of byte range: \" + v);\nentity.setCode(v.byteValue());","typeGuard":"static boolean fitsInByte(Long v) { return v != null && v >= (long) Byte.MIN_VALUE && v <= (long) Byte.MAX_VALUE; }","tryCatchPattern":"try { session.persist(entity); } catch (org.hibernate.type.descriptor.java.CoercionException e) { throw new BadRequestException(\"numeric field out of range\", e); }","preventionTips":["Type DTO fields as Byte/Integer instead of Long when the domain is a small code.","Configure Jackson to use int-sized types (DeserializationFeature.USE_LONG_FOR_INTS off) unless needed.","Never reuse Long ids/counters for tinyint-mapped fields.","Test writes with boundary values 127/128/-128/-129 on Long paths."],"tags":["hibernate","type-coercion","byte","overflow","numeric-range"],"backgroundTag":"numeric-overflow-underflow","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}