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

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

hibernate/hibernate-orm · error · CoercionException

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

Error message

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

What it means

CoercionHelper.toByte(Integer) throws CoercionException('Cannot coerce Integer value ... overflow') when an Integer exceeds Byte.MAX_VALUE (127). Like the Short variant, it is a fail-fast guard on the narrowing conversion invoked from ByteJavaType.coerceOrNull when a byte attribute receives an Integer.

Source

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

			);
		}

		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
					)
			);
		}

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

View on GitHub (pinned to fad1729dce)

Solutions

Widen the attribute and column to int (or short) if values exceed 127.
Range-check and clamp/reject Integer values before binding to the byte attribute.
Convert to Byte explicitly after validation.

Example fix

// before
int limit = 300;
query.setParameter("limit", limit); // byte attribute -> CoercionException: overflow

// after
@Basic private int limit; // widened
// or guard: if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) throw ...; query.setParameter("limit", (byte) v);

Defensive patterns

Strategy: validation

Validate before calling

static boolean fitsByte(int 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(int v) {
    return (v >= Byte.MIN_VALUE && v <= Byte.MAX_VALUE) ? (byte) v : null;
}

Prevention

Cast int literals to byte only after a range check.
Keep HQL parameter types aligned with attribute types (byte param for byte field).
Widen byte columns/fields once real data starts approaching 127.

When it happens

Trigger: Binding an int literal or Integer parameter above 127 (e.g., 200) to a byte attribute in HQL; int-typed query results coerced into byte fields; Criteria parameters typed Integer.

Common situations: Java code naturally producing int values bound to byte columns; schema drift from tinyint to int; UI inputs parsed as Integer and passed through unchecked.

Related errors

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