hibernate/hibernate-orm · error · CoercionException

Cannot coerce value '%s' [%s] to Byte

Error message

Cannot coerce value '%s' [%s] to Byte

What it means

ByteJavaType.coerce supports Byte, Short, Integer, Long, Double, Float, BigInteger, BigDecimal and parseable numeric Strings. When coerceOrNull returns null — the value is some other type (Character, Boolean, LocalDate, ...) or a non-numeric string like '12a' — coerce throws CoercionException naming the value and its class. Note: out-of-range numbers do not produce this message; they raise the separate overflow/underflow CoercionExceptions from CoercionHelper.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/ByteJavaType.java:147

	@Override
	public int getDefaultSqlPrecision(Dialect dialect, JdbcType jdbcType) {
		return 3;
	}

	@Override
	public int getDefaultSqlScale(Dialect dialect, JdbcType jdbcType) {
		return 0;
	}

	@Override
	public @Nullable Byte coerce(@Nullable Object value) {
		if ( value == null ) {
			return null;
		}
		final var coerced = coerceOrNull( value );
		if ( coerced == null ) {
			throw new CoercionException(
					String.format(
							Locale.ROOT,
							"Cannot coerce value '%s' [%s] to Byte",
							value,
							value.getClass().getName()
					)
			);
		}
		return coerced;
	}

	@Override
	public @Nullable Byte coerceOrNull(@Nonnull Object value) {
		if ( value instanceof Byte byteValue ) {
			return byteValue;
		}

		if ( value instanceof Short shotValue ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Convert the value to Byte (or a supported Number / numeric String) before binding.
2. Add an AttributeConverter matching the real source type.
3. Fix the query or parameter declaration so the bound type matches the byte attribute.

Example fix

// before
query.setParameter("limit", "12a"); // String not parseable -> CoercionException

// after
query.setParameter("limit", Byte.parseByte(valueFromUi)); // validate/parse up front

if (value instanceof String s && !s.matches("[+-]?\d+")) {
    throw new IllegalArgumentException("Not a numeric value: " + s);
}

static boolean isByteCoercible(Object v) {
    return v == null || v instanceof Byte || v instanceof Short || v instanceof Integer
        || v instanceof Long || v instanceof Double || v instanceof Float
        || v instanceof BigInteger || v instanceof BigDecimal
        || (v instanceof String s && s.matches("[+-]?\\d+"));
}

When it happens

Trigger: Binding an unsupported parameter type to a byte attribute — e.g. Character '7', Boolean, or String 'abc' — in HQL/Criteria or a dynamic parameter map; result-set coercion of a non-numeric column into a byte field.

Common situations: Loosely-typed parameter maps (Map<String,Object> queries); web/UI layers sending raw strings; schema drift where the column now holds non-numeric data.

Related errors

• Cannot coerce Short value `%s` to Byte : overflow
• Cannot coerce Short value `%s` to Byte : underflow
• Cannot coerce Integer value `%s` to Byte : overflow
• jakarta.persistence.validation.group.{} is of unknown type:
• Given object was not an instance of {} [{}]

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