hibernate/hibernate-orm · error · CoercionException

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

Error message

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

What it means

LongJavaType.coerce() is invoked when Hibernate must convert a value into a Long during query parameter binding or result coercion. It first tries coerceOrNull (numeric types, parseable numeric strings); when no conversion path exists it throws CoercionException naming the offending value and its class. The exception means the value's runtime type is fundamentally unconvertible, not merely out of range.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/java/LongJavaType.java:129

	@Override
	public boolean isWider(JavaType<?> javaType) {
		return switch ( javaType.getTypeName() ) {
			case
				"byte", "java.lang.Byte",
				"short", "java.lang.Short",
				"int", "java.lang.Integer" -> true;
			default -> false;
		};
	}

	@Override
	public @Nullable Long 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 Long",
							value,
							value.getClass().getName()
					)
			);
		}
		return coerced;
	}

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

		if ( value instanceof Byte byteValue ) {

View on GitHub (pinned to fad1729dce)

Solutions

  1. Pass a numeric type or a numeric string that coerceOrNull can parse, or bind with an explicit TypedParameterValue/parameter type
  2. For native queries, SELECT a numeric expression (CAST in SQL) or remap the attribute to the actual returned type
  3. Validate/convert the value before binding: Number.longValue() or Long.parseLong after a regex check
  4. If the source column legitimately varies, map it as String and convert in an AttributeConverter

Example fix

// before
query.setParameter("limit", someRequestDto); // CoercionException: Cannot coerce value '...[com.acme.Dto]' to Long

// after
query.setParameter("limit", someRequestDto.getLimit()); // returns long/Long
Defensive patterns

Strategy: type-guard

Validate before calling

static boolean coercibleToLong(Object v) {
    if (v == null || v instanceof Number || v instanceof java.math.BigInteger) return true;
    if (v instanceof String s) return s.matches("[+-]?\d+");
    return false;
}

if (!coercibleToLong(param)) throw new IllegalArgumentException("Not coercible to Long: " + param);

Type guard

static Long toLongOrNull(Object v) {
    if (v instanceof Number n) return n.longValue();
    if (v instanceof String s && s.matches("[+-]?\d+")) return Long.parseLong(s);
    return null;
}

Try / catch

try { Long bound = LongJavaType.INSTANCE.coerce(value); }
catch (CoercionException e) {
    throw new IllegalArgumentException("Parameter is not numeric: cannot bind to Long", e);
}

Prevention

When it happens

Trigger: query.setParameter("n", someObject) where the parameter's implied type is Long but the argument is an enum, date, UUID or arbitrary object; native query columns mapped to Long attributes returning non-numeric types; criteria/HQL function results coerced to Long; AttributeConverter producing a type Hibernate cannot coerce

Common situations: Passing the wrong variable to a typed parameter after refactoring; native queries whose SELECT expression type differs from the mapped attribute; DB views where a column changed type; String values containing non-numeric text bound to Long parameters.

Related errors

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