hibernate/hibernate-orm · error · IllegalArgumentException

support for multiple properties not implemented

Error message

support for multiple properties not implemented

What it means

The backward-compatible default EntityPersister.getSelectByUniqueKeyString(String[] propertyNames) accepts an array but explicitly supports only a single property: length > 1 throws IllegalArgumentException('support for multiple properties not implemented'). Composite (multi-column) unique keys must use the newer overload getSelectByUniqueKeyString(String[] propertyNames, String[] columnNames).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java:1341

	 *
	 * @param propertyName The name of the property which maps to the
	 *           column(s) to use in the select statement restriction.
	 * @return The SQL select string
	 */
	String getSelectByUniqueKeyString(String propertyName);

	/**
	 * Get a SQL select string that performs a select based on a unique
	 * key determined by the given property names.
	 *
	 * @param propertyNames The names of the properties which maps to the
	 *               column(s) to use in the select statement restriction.
	 * @return The SQL select string
	 */
	default String getSelectByUniqueKeyString(String[] propertyNames) {
		// default impl only for backward compatibility
		if ( propertyNames.length > 1 ) {
			throw new IllegalArgumentException( "support for multiple properties not implemented" );
		}
		return getSelectByUniqueKeyString( propertyNames[0] );
	}

	String getSelectByUniqueKeyString(String[] propertyNames, String[] columnNames);


	/**
	 * The names of the primary key columns in the root table.
	 *
	 * @return The primary key column names.
	 */
	String[] getRootTableKeyColumnNames();

	/**
	 * Get the database-specific SQL command to retrieve the last
	 * generated IDENTITY value.
	 *

View on GitHub (pinned to fad1729dce)

Solutions

1. Switch to getSelectByUniqueKeyString(propertyNames, columnNames) when more than one property is involved
2. Pass only the single property name to the legacy overload
3. If you own the persister, implement the legacy method for multi-property keys instead of relying on the default

Example fix

// before
if ( propertyNames.length > 1 ) {
    sql = persister.getSelectByUniqueKeyString(propertyNames); // throws IllegalArgumentException
}

// after
sql = persister.getSelectByUniqueKeyString(
        propertyNames,
        correspondingColumnNames ); // overload for composite unique keys

String sql;
if ( propertyNames.length > 1 ) {
    sql = persister.getSelectByUniqueKeyString(propertyNames, columnNames);
}
else {
    sql = persister.getSelectByUniqueKeyString(propertyNames);
}

When it happens

Trigger: Calling the legacy single-array overload with two or more property names — typically generic code that resolves all columns of a multi-column unique key and forwards the whole property set to the old entry point.

Common situations: Framework or custom-persister code written against the pre-array signature; migrating code that feeds complete unique-key column sets; retrofitting single-property helpers to composite keys.

Related errors

• EntityPersister implementation '{className}' does not suppor
• constraint involves a formula: {}
• Referenced entity '" + referencedEntityName + "' has no prop
• Entity '{name}' does not have a natural id
• Initialization of entity enhancement used to act like a prox

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