{"record":{"id":"7647e2ae72a38e09","repo":"hibernate/hibernate-orm","slug":"cannot-coerce-short-value-s-to-byte-underflow","errorCode":null,"errorMessage":"Cannot coerce Short value `%s` to Byte : underflow","messagePattern":"Cannot coerce Short value `(.+?)` to Byte : underflow","errorType":"exception","errorClass":"CoercionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java","lineNumber":34,"sourceCode":" */\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\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","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java#L16-L52","documentation":"CoercionHelper.toByte(Short) throws CoercionException('Cannot coerce Short value ... underflow') when a Short is less than Byte.MIN_VALUE (-128). Narrowing it would silently wrap around, so Hibernate fails fast; reached whenever a byte attribute receives a too-negative Short.","triggerScenarios":"Binding a Short such as (short) -200 to a byte attribute in HQL/Criteria; negative smallint column values coerced into a byte field; dynamic parameter maps carrying negative shorts.","commonSituations":"Negative quantity/rating values flowing into a byte column after schema drift; ported data with values below -128; producers that previously relied on silent truncation elsewhere.","solutions":["Widen the attribute/column to short or int.","Validate the range and clamp or reject values below -128 before binding.","Bind Byte values explicitly."],"exampleFix":"// before\nshort delta = -200;\nquery.setParameter(\"delta\", delta); // -> CoercionException: underflow\n\n// after\n@Basic private short delta; // widened mapping\n// or reject early: if (delta < Byte.MIN_VALUE) throw new IllegalArgumentException(\"out of byte range\");","handlingStrategy":"validation","validationCode":"static boolean fitsByte(short v) {\n    return v >= Byte.MIN_VALUE; // underflow guard: >= -128\n}\n// before binding: if (v < Byte.MIN_VALUE) throw new IllegalArgumentException(\"Value \" + v + \" underflows byte\");","typeGuard":"static Byte toByteOrNull(short v) {\n    return (v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE) ? (byte) v : null;\n}","tryCatchPattern":null,"preventionTips":["Validate negative bounds too, not just the upper limit.","Widen the mapping when legitimate values fall outside [-128,127].","Add @Min(-128) bean validation next to @Max(127) on byte fields."],"tags":["hibernate","byte","coercion","underflow","narrowing"],"backgroundTag":"numeric-overflow-coercion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}