hibernate/hibernate-orm · error · QueryArgumentException

Given type is incompatible with parameter type

Error message

Given type is incompatible with parameter type

What it means

When a parameter is bound with an explicit BindableType (a typed setParameter overload or setParameter with a Class/type argument), checkClarifiedType verifies that the given Java type is assignable to the parameter's resolved type. A mismatch throws QueryArgumentException carrying the parameter type, the supplied type, and the value, so the offending argument is identifiable from the message.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingImpl.java:347

	}

	private <V> void clarifyType(Object valueOrValues, BindableType<V> clarifiedType) {
		if ( clarifiedType != null ) {
			checkClarifiedType( clarifiedType, valueOrValues );
			@SuppressWarnings("unchecked") // safe
			final var newType = (BindableType<T>) clarifiedType;
			bindType = newType;
		}
	}

	private <A> void checkClarifiedType(
			@Nonnull BindableType<A> clarifiedType,
			Object valueOrValues) {
		final var parameterType = queryParameter.getParameterType();
		if ( parameterType != null ) {
			final var clarifiedJavaType = clarifiedType.getJavaType();
			if ( !parameterType.isAssignableFrom( clarifiedJavaType ) ) {
				throw new QueryArgumentException(
						"Given type is incompatible with parameter type",
						parameterType, clarifiedJavaType, valueOrValues
				);
			}
		}
		else {
			assert queryParameter.getHibernateType() == null;
		}
	}

	private T cast(Object value) {
		if ( value == null ) {
			return null;
		}
		else {
			final var bindableType =
					getCriteriaBuilder()
							.resolveExpressible( bindType );

View on GitHub (pinned to fad1729dce)

Solutions

1. Make the explicit type match the parameter's declared/inferred type, or drop the hint and let Hibernate infer from the bound value.
2. Check the parameter type first: query.getParameterMetadata().getQueryParameter(name).getParameterType().
3. After changing an entity attribute type, grep for typed setParameter calls that mention the old Class.

Example fix

// before
var q = session.createQuery("from Person p where p.name = :name", Person.class);
q.setParameter("name", "Alice", Integer.class); // Integer not assignable to String

// after
q.setParameter("name", "Alice"); // let Hibernate infer

static boolean typeCompatible(org.hibernate.query.Query<?> q, String name, Class<?> javaType) {
    Class<?> parameterType = q.getParameterMetadata().getQueryParameter(name).getParameterType();
    return parameterType == null || parameterType.isAssignableFrom(javaType);
}

static boolean typeCompatible(org.hibernate.query.Query<?> q, String name, Class<?> javaType) {
    Class<?> parameterType = q.getParameterMetadata().getQueryParameter(name).getParameterType();
    return parameterType == null || parameterType.isAssignableFrom(javaType);
}

When it happens

Trigger: setParameter("age", 30, String.class) on a parameter Hibernate resolved as Integer; giving LocalDate.class for a LocalDateTime parameter; any typed overload whose Class does not match the parameter type inferred from the HQL expression.

Common situations: Copy-pasted typed bindings after an entity attribute changed type; enum vs String hints; migrating from Hibernate 5 where explicit type hints were more forgiving.

Related errors

• Argument to query parameter has an incompatible type: {}
• Unable to locate JdbcValueDescriptor for column `%s`
• jakarta.persistence.validation.group.{} is of unknown type:
• Given object was not an instance of {} [{}]
• Configuration property hibernate.jdbc.time_zone value [{}] i

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