{"record":{"id":"849faae3df9abc90","repo":"hibernate/hibernate-orm","slug":"cannot-coerce-short-value-s-to-byte-overflow","errorCode":null,"errorMessage":"Cannot coerce Short value `%s` to Byte : overflow","messagePattern":"Cannot coerce Short 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":24,"sourceCode":"\nimport java.math.BigDecimal;\nimport java.math.BigInteger;\nimport java.util.Locale;\n\n/**\n * Helper for type coercions.  Mainly used for narrowing coercions which\n * might lead to under/over-flow problems\n *\n * @author Steve Ebersole\n */\npublic class CoercionHelper {\n\tprivate CoercionHelper() {\n\t\t// disallow direct instantiation\n\t}\n\n\tpublic static Byte toByte(Short 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 Short 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 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","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java#L6-L42","documentation":"CoercionHelper.toByte(Short) performs a checked narrowing conversion and refuses silent data loss: a Short greater than Byte.MAX_VALUE (127) throws CoercionException('Cannot coerce Short value ... overflow'). It is reached from ByteJavaType.coerce/coerceOrNull when a byte-typed attribute or parameter receives a Short value.","triggerScenarios":"Binding a Short such as (short) 200 to a byte attribute in HQL/Criteria; a smallint result-set column coerced into a byte field; dynamic filters passing short values above 127.","commonSituations":"Schema drift: the column was widened to SMALLINT while the entity keeps byte; upstream producers sending values over 127; porting from a stack that silently truncated.","solutions":["Change the attribute (and column) to short or int if values legitimately exceed 127.","Validate and clamp values into [-128, 127] before binding them to the byte attribute.","Pass Byte values explicitly at the call site."],"exampleFix":"// before\nshort limit = 200;\nquery.setParameter(\"max\", limit); // byte attribute -> CoercionException: overflow\n\n// after\n// widen the attribute\n@Basic private short max;\n// or clamp: query.setParameter(\"max\", (byte) Math.min(limit, 127));","handlingStrategy":"validation","validationCode":"static boolean fitsByte(short 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(short v) {\n    return (v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE) ? (byte) v : null;\n}","tryCatchPattern":null,"preventionTips":["Range-check short inputs before binding to byte attributes.","Align entity field types with column widths (smallint column -> short field).","Add bean-validation @Max(127)/@Min(-128) on byte fields."],"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"}