hibernate/hibernate-orm · error · QueryParameterException

Could not determine mapping type for named parameter ':{}'

Error message

Could not determine mapping type for named parameter ':{}'

What it means

When Hibernate needs the mapping type of a parameter (to prepare the JDBC statement or build a cache key), it first infers a BasicType from any non-null bound value. If the parameter has no usable value and no explicit bind type, the type is undeterminable and Hibernate throws QueryParameterException naming the parameter. This differs from the 'no argument' check: the parameter is bound, but bound uselessly (null, untyped).

Source

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

				// avoid dynamic models
				return typeConfiguration.getBasicTypeForJavaType( javaTypeClass );
			}
		}

		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;

View on GitHub (pinned to fad1729dce)

Solutions

1. Use a typed overload for null: setParameter("x", null, String.class) (Hibernate Query) so bindType is set.
2. Or omit the predicate entirely when the value is null, via dynamic query building.
3. For native queries, bind with an explicit type or cast in SQL (e.g. cast(null as integer)).

Example fix

// before
q.setParameter("status", null); // later: could not determine mapping type

// after
q.setParameter("status", null, String.class); // explicit type
// or: skip the "and p.status = :status" predicate when status == null

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

When it happens

Trigger: setParameter("status", null) without a type hint on a parameter whose type Hibernate cannot resolve statically (common in native queries or parameters used only in expressions with no inferable type); binding only null values so the value-based inference has nothing to work with.

Common situations: Optional filters bound as null 'to be safe'; queries migrated after a value/type was removed; native SQL where parameter types are never inferable from the string alone.

Related errors

• Could not determine mapping type for ordinal parameter '?{}'
• Could not resolve named type : " + hibernateTypeName
• JDBC driver does not support named parameters for setArray.
• GaussDB only supports accessing REF_CURSOR parameters by pos
• Named native query definition object is null

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