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

Change the attribute (and column) to short or int if values legitimately exceed 127.

hibernate/hibernate-orm · error · CoercionException

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

Error message

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

What it means

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.

Source

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

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Locale;

/**
 * Helper for type coercions.  Mainly used for narrowing coercions which
 * might lead to under/over-flow problems
 *
 * @author Steve Ebersole
 */
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
					)
			);
		}

View on GitHub (pinned to fad1729dce)

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.

Example fix

// before
short limit = 200;
query.setParameter("max", limit); // byte attribute -> CoercionException: overflow

// after
// widen the attribute
@Basic private short max;
// or clamp: query.setParameter("max", (byte) Math.min(limit, 127));

Defensive patterns

Strategy: validation

Validate before calling

static boolean fitsByte(short v) {
    return v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE;
}
// before binding: if (!fitsByte(v)) throw new IllegalArgumentException("Value " + v + " out of byte range");

Type guard

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

Prevention

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.

When it happens

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

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

Related errors

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