What causes "Cannot coerce Short value `%s` to Byte : underflow" in hibernate/hibernate-orm?

Widen the attribute/column to short or int.

hibernate/hibernate-orm · error · CoercionException

Cannot coerce Short value `%s` to Byte : underflow

Error message

Cannot coerce Short value `%s` to Byte : underflow

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/CoercionHelper.java:34

 */
public class CoercionHelper {
	private CoercionHelper() {
		// disallow direct instantiation
	}

	public static Byte toByte(Short value) {
		if ( value > Byte.MAX_VALUE ) {
			throw new CoercionException(
					String.format(
							Locale.ROOT,
							"Cannot coerce Short value `%s` to Byte : overflow",
							value
					)
			);
		}

		if ( value < Byte.MIN_VALUE ) {
			throw new CoercionException(
					String.format(
							Locale.ROOT,
							"Cannot coerce Short value `%s` to Byte : underflow",
							value
					)
			);
		}

		return value.byteValue();
	}

	public static Byte toByte(Integer value) {
		if ( value > Byte.MAX_VALUE ) {
			throw new CoercionException(
					String.format(
							Locale.ROOT,
							"Cannot coerce Integer value `%s` to Byte : overflow",
							value

View on GitHub (pinned to fad1729dce)

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.

Example fix

// before
short delta = -200;
query.setParameter("delta", delta); // -> CoercionException: underflow

// after
@Basic private short delta; // widened mapping
// or reject early: if (delta < Byte.MIN_VALUE) throw new IllegalArgumentException("out of byte range");

Defensive patterns

Strategy: validation

Validate before calling

static boolean fitsByte(short v) {
    return v >= Byte.MIN_VALUE; // underflow guard: >= -128
}
// before binding: if (v < Byte.MIN_VALUE) throw new IllegalArgumentException("Value " + v + " underflows byte");

Type guard

static Byte toByteOrNull(short v) {
    return (v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE) ? (byte) v : null;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/7647e2ae72a38e09. Report an issue: GitHub.