hibernate/hibernate-orm · error · IllegalStateException

Parameter value not yet bound : {param}

Error message

Parameter value not yet bound : {param}

What it means

Thrown (IllegalStateException) by getParameterValue(Parameter<T> param) when the parameter IS part of the query but has no binding yet: the resolved parameter's QueryParameterBinding is null or binding.isBound() is false. You are asking to read a value that was never set with setParameter. Note the adjacent TODO in the source: if the binding is multi-valued the raw bind-values List is returned with an unchecked cast, so type safety on that path is not guaranteed.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java:937

			return castParameter;
		}
		catch ( HibernateException e ) {
			throw getExceptionConverter().convert( e );
		}
	}

	@Override
	public <T> T getParameterValue(@Nonnull Parameter<T> param) {
		session.checkOpen( false );
		final var parameter = getParameterMetadata().resolve( param );
		if ( parameter == null ) {
			throw new IllegalArgumentException( "The parameter [" + param + "] is not part of this Query" );
		}
		final var binding =
				getQueryParameterBindings()
						.getBinding( getQueryParameter( parameter ) );
		if ( binding == null || !binding.isBound() ) {
			throw new IllegalStateException( "Parameter value not yet bound : " + param );
		}
		if ( binding.isMultiValued() ) {
			// TODO: THIS IS UNSOUND, we should really throw in this case
			//noinspection unchecked
			return (T) binding.getBindValues();
		}
		else {
			return binding.getBindValue();
		}
	}

	@Override
	public Object getParameterValue(@Nonnull String name) {
		session.checkOpen( false );
		final var binding = getQueryParameterBindings().getBinding( name );
		if ( !binding.isBound() ) {
			throw new IllegalStateException( "The parameter named '" + name + "' has no argument" );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Bind every parameter before reading: query.setParameter(param, value) — including explicit null when the value is genuinely null
2. Check bound-ness first with query.isBound(param) (JPA Query method) before calling getParameterValue
3. Restructure wrapper code to read values only after the binding phase completes

Example fix

// before
Object v = query.getParameterValue( param ); // IllegalStateException: not yet bound

// after
if ( query.isBound( param ) ) {
    Object v = query.getParameterValue( param );
} else {
    query.setParameter( param, defaultValue );
}

Parameter<?> p = query.getParameter( "name" );
if ( !query.isBound( p ) ) {
    query.setParameter( p, defaultValue );
}
Object v = query.getParameterValue( p );

try {
    return query.getParameterValue( param );
} catch ( IllegalStateException e ) {
    return null; // treat 'not yet bound' as absent
}

When it happens

Trigger: Calling query.getParameterValue(param) before any query.setParameter(param, value). Reading a parameter in dynamic filter code where the parameter is optional and may legitimately be unset. Checking bound values after an exception aborted the binding loop midway.

Common situations: Generic query wrappers that iterate all getParameters() and log their values; test harnesses asserting bound arguments before binding happens; optional-parameter handling where 'not set' and 'set to null' were conflated.

Related errors

• The parameter named '{name}' has no argument
• The parameter at position{position} has no argument
• The parameter [{param}] is not part of this Query
• Null value not allowed for multi-valued parameter ':{name}'
• Unable to locate JdbcValueDescriptor for column `%s`

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