{"record":{"id":"02bcdf2fc9fea0c8","repo":"hibernate/hibernate-orm","slug":"cannot-coerce-float-value-s-to-byte-underflow","errorCode":null,"errorMessage":"Cannot coerce Float value `%s` to Byte : underflow","messagePattern":"Cannot coerce Float 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":150,"sourceCode":"\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\"Cannot coerce Float value `%s` to Byte : not a whole number\",\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.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 Float 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 Float 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(BigInteger value) {\n\t\treturn coerceWrappingError( value::byteValueExact );\n\t}\n\n\tpublic static Byte toByte(BigDecimal value) {\n\t\treturn coerceWrappingError( value::byteValueExact );\n\t}","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java#L132-L168","documentation":"Hibernate throws this CoercionException when a whole-number Float is narrowed to Byte below -128. CoercionHelper.toByte(Float) checks isWholeNumber, then the upper bound, then fails `value < Byte.MIN_VALUE`. It is reached through ByteJavaType.coerce when a Float value is coerced for a Byte-mapped attribute. Like its siblings it is a fail-fast rejection of lossy narrowing, with the bad value included in the message.","triggerScenarios":"Assigning whole Floats < -128 (e.g. -255.0f) to Byte/byte attributes: `station.setCorrection(-255.0f)`, or binding such a value as a query parameter on a Byte path.","commonSituations":"Negative calibration offsets or temperature-like floats stored in tinyint Byte fields; overflow of magnitude in float pipelines (subtracting baselines); legacy Float-typed service interfaces feeding Byte entities; silent-truncation-to-strict upgrade from Hibernate 5.","solutions":["Re-type the attribute/column to fit the value domain (Float/Integer instead of Byte).","Guard and narrow explicitly: round, verify -128..127, then cast to byte.","Fix the upstream computation producing out-of-range magnitudes (sign/unit errors).","Reject out-of-range inputs at the service boundary with domain-specific errors."],"exampleFix":"// before\nFloat correction = baseline - sample;   // e.g. -400.0f\nstation.setCorrection(correction);      // Byte field -> underflow\n\n// after\nint i = Math.round(correction);\nif (i >= Byte.MIN_VALUE && i <= Byte.MAX_VALUE) {\n    station.setCorrection((byte) i);\n} else {\n    throw new IllegalArgumentException(\"correction out of range: \" + i);\n}","handlingStrategy":"validation","validationCode":"int i = Math.round(correction);\nif (i < Byte.MIN_VALUE || i > Byte.MAX_VALUE) throw new IllegalArgumentException(\"correction out of range: \" + i);\nstation.setCorrection((byte) i);","typeGuard":"static boolean fitsInByteFloat(Float f) { return f != null && f == Math.rint(f) && f >= Byte.MIN_VALUE && f <= Byte.MAX_VALUE; }","tryCatchPattern":"catch CoercionException; convert to domain error; log the numeric value for diagnosis.","preventionTips":["Investigate sign/unit errors whenever magnitudes unexpectedly exceed the byte range.","Keep baseline-subtraction math in int/long, not float, for integral fields."],"tags":["hibernate","type-coercion","byte","float","underflow"],"backgroundTag":"numeric-overflow-underflow","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}