hibernate/hibernate-orm · error · IllegalArgumentException

Named parameter [" + name + "] is not registered with this p

Error message

Named parameter [" + name + "] is not registered with this procedure call

What it means

getQueryParameter(String) scans the registered parameters and throws IllegalArgumentException when none carries that name. Hibernate's native ProcedureCall requires every parameter to be explicitly registered before binding — unlike HQL, where parameters are discovered from the query text. The message includes the exact name that failed to resolve.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/procedure/internal/ProcedureParameterMetadataImpl.java:155

	@Override
	public ProcedureParameterImplementor<?> findQueryParameter(String name) {
		if ( parameters != null ) {
			for ( var parameter : parameters ) {
				if ( name.equals( parameter.getName() ) ) {
					return parameter;
				}
			}
		}
		return null;
	}

	@Override
	public ProcedureParameterImplementor<?> getQueryParameter(String name) {
		final var parameter = findQueryParameter( name );
		if ( parameter != null ) {
			return parameter;
		}
		throw new IllegalArgumentException( "Named parameter [" + name + "] is not registered with this procedure call" );
	}

	@Override
	public ProcedureParameterImplementor<?> findQueryParameter(int positionLabel) {
		if ( parameters != null ) {
			for ( var parameter : parameters ) {
				if ( parameter.getName() == null
						&& positionLabel == parameter.getPosition() ) {
					return parameter;
				}
			}
		}
		return null;
	}

	@Override
	public ProcedureParameterImplementor<?> getQueryParameter(int positionLabel) {
		final var queryParameter = findQueryParameter( positionLabel );

View on GitHub (pinned to fad1729dce)

Solutions

1. Register the parameter before binding: call.registerParameter("total", BigDecimal.class, ParameterMode.OUT)
2. Use the find-style lookup (findQueryParameter) or inspect registered parameters before binding instead of the throwing get variant
3. Make the bound name match the registration exactly, including case

Example fix

// before
StoredProcedureQuery q = em.createStoredProcedureQuery("checkout");
q.setParameter("total", new BigDecimal(10)); // not registered

// after
q.registerStoredProcedureParameter("total", BigDecimal.class, ParameterMode.INOUT);
q.setParameter("total", new BigDecimal(10));

// Register before binding (Jakarta API)
StoredProcedureQuery q = em.createStoredProcedureQuery("checkout");
q.registerStoredProcedureParameter("total", BigDecimal.class, ParameterMode.INOUT);
q.setParameter("total", total);

try {
    call.getParameterBindings().getBinding("total");
} catch (IllegalArgumentException e) {
    // "total" was never registered: register it, or fix the typo in the name
}

When it happens

Trigger: call.getParameterBindings().getBinding("total") or StoredProcedureQuery.setParameter("total", value) when "total" was never registered, or was registered positionally so only getPosition() is set.

Common situations: Assuming HQL-style auto-discovered parameters also work for stored procedures; a typo in the parameter name (case-sensitive); switching a call from named to positional registration while keeping setParameter(name, ...) calls; optional parameters that are set conditionally but never registered.

Related errors

• Cannot determine the bindable type for procedure parameter %
• Cannot mix named parameter with positional parameter registr
• Cannot mix positional parameter with named parameter registr
• Positional parameter " + positionLabel + " is not registered
• JDBC driver does not support named parameters for setArray.

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