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.

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
• Annotation ' ' is not assignable to
• Argument to query parameter has an incompatible type
• Array element type error
• Attribute ' . ' of type ' ' is annotated '@Bag' (bags are…

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

Appendix: 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)