hibernate/hibernate-orm · error · IllegalArgumentException

Couldn't find subclass index for joined table reference

Error message

Couldn't find subclass index for joined table reference 

What it means

When translating a pessimistic locking clause of the form FOR UPDATE OF <alias/table>, StandardLockingClauseStrategy maps each joined table reference to an EntityTableMapping — first against the entity's own tables, then against its subclass mappings. If no mapping's table name matches the reference (wrong alias, unquoted/case mismatch, or a table that belongs to a join/CTE rather than the entity hierarchy), it throws IllegalArgumentException naming the unmatched reference.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/sql/ast/internal/StandardLockingClauseStrategy.java:274

			}
		}
	}

	private TableMapping determineTableMapping(EntityPersister entityPersister, TableReferenceJoin tableReferenceJoin) {
		final NamedTableReference joinedTableReference = tableReferenceJoin.getJoinedTableReference();
		for ( EntityTableMapping tableMapping : entityPersister.getTableMappings() ) {
			if ( joinedTableReference.containsAffectedTableName( tableMapping.getTableName() ) ) {
				return tableMapping;
			}
		}
		for ( EntityMappingType subMappingType : entityPersister.getSubMappingTypes() ) {
			for ( EntityTableMapping tableMapping : subMappingType.getEntityPersister().getTableMappings() ) {
				if ( joinedTableReference.containsAffectedTableName( tableMapping.getTableName() ) ) {
					return tableMapping;
				}
			}
		}
		throw new IllegalArgumentException( "Couldn't find subclass index for joined table reference " + joinedTableReference );
	}

	private EntityPersister determineEntityPersister(ModelPartContainer modelPart) {
		if ( modelPart instanceof EntityPersister entityPersister ) {
			return entityPersister;
		}
		else if ( modelPart instanceof PluralAttributeMapping pluralAttributeMapping ) {
			return pluralAttributeMapping.getCollectionDescriptor().getElementPersister();
		}
		else if ( modelPart instanceof EntityAssociationMapping entityAssociationMapping ) {
			return entityAssociationMapping.getAssociatedEntityMappingType().getEntityPersister();
		}
		else {
			throw new IllegalArgumentException( "Expected table group with table joins to have an entity typed model part but got: " + modelPart );
		}
	}

	private String[] determineKeyColumnNames(TableGroup tableGroup) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Reference only aliases of entity-root tables of the locked hierarchy in the OF list
2. Drop the explicit OF list — plain 'for update' locks all tables and avoids alias resolution
3. Check table-name quoting/case in @Table against the alias used in the query
4. Upgrade Hibernate — the locking clause strategy is internal and actively fixed between 6.x releases

Example fix

// before (HQL)
select o from Order o join o.lines l where o.due < :d
    order by o.id for update of l  // 'l' is a collection table join -> no mapping

// after
select o from Order o join fetch o.lines l where o.due < :d
    order by o.id for update  // lock the entity root(s)

// validate aliases before issuing a FOR UPDATE OF query
Set<String> tableNames = new HashSet<>();
EntityPersister p = (EntityPersister) sessionFactory.getMetamodel()
        .entityPersister(Order.class);
for (EntityTableMapping t : p.getTableMappings()) tableNames.add(t.getTableName());
if (!tableNames.contains(aliasTableName)) {
    throw new IllegalArgumentException("alias " + alias + " is not a mapped table of the entity");
}

try {
    return query.getResultList();
}
catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Couldn't find subclass index")) {
        // rewrite without the explicit FOR UPDATE OF list and retry
        return queryWithoutOfList().getResultList();
    }
    throw e;
}

When it happens

Trigger: HQL/JPQL 'select ... for update of x' where x is an alias of a joined collection table, a CTE, or an unrelated entity; using a subclass table alias in a polymorphic query; database identifier case/quoting differences between the alias and the mapped table name.

Common situations: Ported native FOR UPDATE OF hints into HQL; pessimistic locking on inheritance hierarchies with joined subclass tables; case-sensitive schemas (Oracle upper-cases unquoted identifiers) where the alias casing does not match mapping metadata.

Related errors

• Entity discriminator cannot be de-referenced
• Could not resolve attribute '%s' of '%s' due to the attribut
• Path '<navigablePath>' did not reference a known model part
• Basic-value cannot be treated (downcast)
• Expected table group with table joins to have an entity type

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