What causes "Unrecognized parameter type : " + parameter" in hibernate/hibernate-orm?

Use ProcedureCall#registerParameter overloads instead of constructing ProcedureParameterImplementor instances directly

hibernate/hibernate-orm · error · IllegalArgumentException

Unrecognized parameter type : " + parameter

Error message

Unrecognized parameter type : " + parameter

What it means

registerParameter only understands parameters that are named (isNamed(), name != null) or ordinal (isOrdinal(), position != null). A parameter with both null falls through to IllegalArgumentException 'Unrecognized parameter type'. This is an internal invariant violation: the public ProcedureCall.registerParameter overloads always set exactly one of the two.

Source

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

	private ParameterStrategy parameterStrategy = ParameterStrategy.UNKNOWN;
	private List<ProcedureParameterImplementor<?>> parameters;

	@Override
	public void registerParameter(ProcedureParameterImplementor<?> parameter) {
		if ( parameter.isNamed() ) {
			if ( parameterStrategy == ParameterStrategy.POSITIONAL ) {
				throw new IllegalArgumentException( "Cannot mix named parameter with positional parameter registrations" );
			}
			parameterStrategy = ParameterStrategy.NAMED;
		}
		else if ( parameter.isOrdinal() ) {
			if ( parameterStrategy == ParameterStrategy.NAMED ) {
				throw new IllegalArgumentException( "Cannot mix positional parameter with named parameter registrations" );
			}
			parameterStrategy = ParameterStrategy.POSITIONAL;
		}
		else {
			throw new IllegalArgumentException( "Unrecognized parameter type : " + parameter );
		}
		if ( parameters == null ) {
			parameters = new ArrayList<>();
		}
		parameters.add( parameter );
	}

	@Override
	public QueryParameterBindings createBindings(SessionFactoryImplementor sessionFactory) {
		return QueryParameterBindingsImpl.from( this, sessionFactory );
	}

	@Override
	public void visitParameters(Consumer<QueryParameter<?>> consumer) {
		if ( parameters != null ) {
			parameters.forEach( consumer );
		}
	}

View on GitHub (pinned to fad1729dce)

Solutions

Use ProcedureCall#registerParameter overloads instead of constructing ProcedureParameterImplementor instances directly
If you implement the SPI, guarantee exactly one of getName()/getPosition() is non-null before registerParameter is invoked
Audit any code calling setName(null) or setPosition(null) on a registered parameter

Defensive patterns

Strategy: try-catch

Validate before calling

if (param.getName() == null && param.getPosition() == null) {
    throw new IllegalStateException("Procedure parameter must have a name or a position");
}
metadata.registerParameter(param);

Try / catch

try {
    metadata.registerParameter(param);
} catch (IllegalArgumentException e) {
    // internal invariant broken: name and position both null — fix the parameter construction
}

Prevention

Use ProcedureCall#registerParameter instead of implementing the internal SPI
If you must build ProcedureParameterImplementor, assert exactly one of name/position is set
Never mutate a registered parameter to clear its name and position

When it happens

Trigger: Registering a hand-built or proxied ProcedureParameterImplementor whose name and position are both null; a custom implementation of the internal SPI that failed to populate either field; a parameter object mutated (name/position cleared) after construction.

Common situations: Code that bypasses the public API and constructs parameter registrations directly against internal classes; a fork or patched Hibernate with a broken builder; extremely rare with the documented API.

Related errors

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