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

GaussDBArrayJdbcType binds array values by calling CallableStatement.setObject(name, array, Types.ARRAY) when a parameter is bound by name. GaussDB's JDBC driver rejects named parameters for array binding with a SQLException, which this binder wraps in HibernateException with a message telling you to use positional parameters instead.

Source

Thrown at hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/GaussDBArrayJdbcType.java:63

			super( javaType, GaussDBArrayJdbcType.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 java.sql.Array arr = getArray( value, options );
			try {
				st.setObject( name, arr, 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 ),
							elements( value, options, GaussDBArrayJdbcType.this ) );
		}

		private Object[] elements(X value, WrapperOptions options, GaussDBArrayJdbcType arrayJdbcType)

View on GitHub (pinned to fad1729dce)

Solutions

1. Bind by position instead of name: use registerStoredProcedureParameter(1, String[].class, ParameterMode.IN) and setParameter(1, values), or ?1 placeholders in native queries
2. If the procedure signature allows, pass the array as a delimited string and split server-side
3. Replace the stored-procedure array parameter with a temp-table or JSON parameter approach supported by the driver
4. Check for an updated GaussDB driver - named setArray support is a driver limitation - but keep positional binding as the portable form

Example fix

// before (named parameter, driver throws -> HibernateException)
StoredProcedureQuery q = em.createStoredProcedureQuery("save_tags");
q.registerStoredProcedureParameter("tags", String[].class, ParameterMode.IN);
q.setParameter("tags", tags);

// after (positional binding)
StoredProcedureQuery q = em.createStoredProcedureQuery("save_tags");
q.registerStoredProcedureParameter(1, String[].class, ParameterMode.IN);
q.setParameter(1, tags);

// detect GaussDB array + named binding before executing
boolean gauss = sessionFactory.getJdbcServices().getDialect() instanceof GaussDBDialect;
if (gauss && usesNamedArrayParam(query)) {
    query = convertToPositionalBinding(query); // :tags -> ?1, setParameter(1, tags)
}

static boolean namedArrayBindingSafe(Dialect d) {
    return !(d instanceof GaussDBDialect);
}

try {
    proc.setParameter("tags", tags).execute();
} catch (org.hibernate.HibernateException e) {
    if (e.getMessage().contains("named parameters for setArray")) {
        // retry with positional binding: setParameter(1, tags)
    } else throw e;
}

When it happens

Trigger: Registering or binding an array-typed parameter by name on GaussDB: a StoredProcedureQuery/ProcedureCall with registerStoredProcedureParameter('param', String[].class, IN) and setParameter('param', values), or a native query with :names bound to an array/collection mapped through the array JdbcType.

Common situations: Stored procedures taking VARRAY/array arguments migrated from PostgreSQL (where named binding works) to GaussDB; @NamedStoredProcedureQuery entities with array IN parameters; native upsert queries binding collections by name on GaussDB.

Related errors

• GaussDB only supports accessing REF_CURSOR parameters by pos
• GaussDB only supports REF_CURSOR parameters as the first par
• JDBC driver does not support named parameters for setArray.
• Unexpected error extracting REF_CURSOR parameter [{}]
• Error extracting procedure output parameter value [" + param

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