hibernate/hibernate-orm · error · QueryParameterException

Could not determine mapping type for ordinal parameter '?{}'

Error message

Could not determine mapping type for ordinal parameter '?{}'

What it means

The ordinal variant of the type-resolution failure: Hibernate tries to infer the parameter's BasicType from bound values, finds none, and the parameter has no explicit bind type, so QueryParameterException is thrown naming the '?N' label. It happens after binding (values exist but are null) or when the binding carries no type the mapper can use.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/QueryParameterBindingsImpl.java:327

		if ( binding.isMultiValued() ) {
			final var iterator = binding.getBindValues().iterator();
			final Object firstNonNullBindValue = iterator.hasNext() ? iterator.next() : null;
			if ( firstNonNullBindValue != null ) {
				return typeConfiguration.getBasicTypeForJavaType( firstNonNullBindValue.getClass() );
			}
		}
		else if ( binding.getBindValue() != null ) {
			return typeConfiguration.getBasicTypeForJavaType( binding.getBindValue().getClass() );
		}

		if ( bindType == null ) {
			if ( queryParameter.isNamed() ) {
				throw new QueryParameterException(
						"Could not determine mapping type for named parameter ':"
							+ queryParameter.getName() + "'" );
			}
			else {
				throw new QueryParameterException(
						"Could not determine mapping type for ordinal parameter '?"
							+ queryParameter.getPosition() + "'" );
			}
		}

		return typeConfiguration.getBasicTypeForJavaType( bindType.getJavaType() );
	}

	private static class MutableCacheKeyImpl implements MutableCacheKeyBuilder {

		final List<Object> values;
		int hashCode;

		public MutableCacheKeyImpl(int parameterBindingMapSize) {
			values = new ArrayList<>( parameterBindingMapSize );
		}

		@Override

View on GitHub (pinned to fad1729dce)

Solutions

1. Bind nulls with an explicit type: setParameter(1, null, Integer.class).
2. Omit the predicate when the value is null instead of binding null.
3. For native SQL, cast the null in the query text or register the parameter type on the NativeQuery.

Example fix

// before
q.setParameter(1, null); // later: could not determine mapping type for '?1'

// after
q.setParameter(1, null, Integer.class); // explicit type
// or omit the predicate when the value is null

static void bindNullable(org.hibernate.query.Query<?> q, int position, Object value, Class<?> javaType) {
    if (value == null) {
        q.setParameter(position, null, javaType); // explicit type for null
    } else {
        q.setParameter(position, value);
    }
}

When it happens

Trigger: setParameter(1, null) with no type argument on an ordinal parameter whose type cannot be determined from the query; native queries binding null ordinals without an explicit type.

Common situations: Optional filters using ordinal labels and null defaults; migration from code that relied on the parameter's static type; native SQL with untyped null binds.

Related errors

• Could not determine mapping type for named parameter ':{}'
• Could not resolve named type : " + hibernateTypeName
• Named native query definition object is null
• Named native query definition name is null: {}
• Error calling Value#setTypeUsingReflection: containingClassN

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