hibernate/hibernate-orm · error · HibernateException

JDBC driver does not support named parameters for setArray.

Error message

JDBC driver does not support named parameters for setArray. Use positional.

What it means

CallableStatement has no setArray(String, Array), so when Hibernate binds an array to a named stored-procedure parameter it falls back to st.setObject(name, array, Types.ARRAY). If the JDBC driver rejects that call, Hibernate wraps the SQLException in HibernateException('JDBC driver does not support named parameters for setArray. Use positional.'). The failure is a driver capability gap, not a data problem - the fix is positional binding, which uses the real setArray(index, ...).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/ArrayJdbcType.java:239

			super( javaType, ArrayJdbcType.this );
			this.pluralJavaType = pluralJavaType;
		}

		@Override
		protected void doBind(PreparedStatement st, X value, int index, WrapperOptions options)
				throws SQLException {
			st.setArray( index, getArray( value, options ) );
		}

		@Override
		protected void doBind(CallableStatement st, X value, String name, WrapperOptions options)
				throws SQLException {
			final var array = getArray( value, options );
			try {
				st.setObject( name, array, Types.ARRAY );
			}
			catch (SQLException ex) {
				throw new HibernateException(
						"JDBC driver does not support named parameters for setArray. Use positional.", ex );
			}
		}

		@Override
		public Object[] getBindValue(X value, WrapperOptions options) throws SQLException {
			final var elementBinder = getElementJdbcType().getBinder( pluralJavaType.getElementJavaType() );
			return convertToArray( this, elementBinder, pluralJavaType, value, options );
		}

		private java.sql.Array getArray(X value, WrapperOptions options) throws SQLException {
			final var session = options.getSession();
			return session.getJdbcCoordinator().getLogicalConnection().getPhysicalConnection()
					.createArrayOf( getElementTypeName( getJavaType(), session ),
							getBindValue( value, options ) );
		}
	}

View on GitHub (pinned to fad1729dce)

Solutions

Register and bind the array parameter by position instead of by name so the binder uses setArray(index, array).
Upgrade the JDBC driver to a version that supports setObject with Types.ARRAY on named parameters.
As a stopgap, pass the array in a serialized form (CSV or JSON string) and unpack it inside the procedure.

Example fix

// before
StoredProcedureQuery q = em.createStoredProcedureQuery("my_pkg.load_ids");
q.registerStoredProcedureParameter("p_ids", Object[].class, ParameterMode.IN);
q.setParameter("p_ids", ids); // named + array -> driver rejects setObject

// after: positional parameters use setArray
StoredProcedureQuery q = em.createStoredProcedureQuery("my_pkg.load_ids");
q.registerStoredProcedureParameter(1, Object[].class, ParameterMode.IN);
q.setParameter(1, ids);

Defensive patterns

Strategy: fallback

Validate before calling

// Probe once per driver: can it bind arrays to named parameters?
static boolean namedArrayBindingSupported(Connection c) throws Exception {
    try (Connection conn = c) {
        // driver-specific; simplest robust policy: treat Oracle-style drivers as unsupported
        return !c.getMetaData().getDatabaseProductName().toLowerCase().contains("oracle");
    }
}

Try / catch

try {
    query.setParameter("p_ids", arrayValue).execute();
} catch (org.hibernate.HibernateException e) {
    if (e.getMessage() != null && e.getMessage().contains("named parameters for setArray")) {
        // re-register the parameter positionally and re-run: binder will use setArray(index, ...)
    } else {
        throw e;
    }
}

Prevention

Prefer positional parameters for stored procedures that take arrays
Keep the JDBC driver up to date and note named-parameter array support in driver release notes
Wrap stored-procedure calls in a repository method so the binding style is fixed in one place

When it happens

Trigger: StoredProcedureQuery or CallableStatement with a named parameter and an array-typed argument (e.g., an Oracle ARRAY / postgres array type), executed on a driver whose setObject(name, ..., Types.ARRAY) throws SQLException.

Common situations: Oracle thin driver versions that do not accept named-parameter setObject with Types.ARRAY; stored procedures taking collection/table parameters; code migrated from positional to named parameters during refactor; older bundled drivers in app servers.

Related errors

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