hibernate/hibernate-orm · error · UnknownTableReferenceException

Couldn't find table reference

Error message

Couldn't find table reference

What it means

When a filter applies to a JOINED-inheritance hierarchy that has no explicit discriminator, Hibernate must keep every subclass-table join in the SQL to be able to tell rows apart. pruneForSubclasses looks up each subclass table's TableReference in the current TableGroup; UnknownTableReferenceException('Couldn't find table reference') means the TableGroup was built without that join, so the filter logic cannot proceed. Most often hit in query paths that build partial table groups (treat, restricted fetches) combined with @Filter.

Source

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

					classOrSuperclassTables.add( subclassTableNames[i] );
				}
			}
			if ( tablesToInnerJoin.isEmpty() ) {
				tablesToInnerJoin.addAll( classOrSuperclassTables );
			}
			else {
				tablesToInnerJoin.retainAll( classOrSuperclassTables );
			}
			if ( useKind == EntityNameUse.UseKind.FILTER && explicitDiscriminatorColumnName == null ) {
				// If there is no discriminator column,
				// we must retain all joins to subclass tables to be able to discriminate the rows
				for ( int i = 0; i < subclassTableNames.length; i++ ) {
					if ( !persister.isClassOrSuperclassTable[i] ) {
						final String subclassTableName = subclassTableNames[i];
						final var mainTableReference =
								tableGroup.getTableReference( null, subclassTableName, false );
						if ( mainTableReference == null ) {
							throw new UnknownTableReferenceException(
									subclassTableName,
									"Couldn't find table reference"
							);
						}
						retainedTableReferences.add( mainTableReference );
					}
				}
			}
		}
	}

	@Override
	public EntityIdentifierMapping getIdentifierMappingForJoin() {
		// If the joined subclass has a physical discriminator and has subtypes
		// we must use the root table identifier mapping for joining to allow table group elimination to work
		return isPhysicalDiscriminator() && !getSubMappingTypes().isEmpty()
				? getRootEntityDescriptor().getIdentifierMapping()
				: super.getIdentifierMappingForJoin();

View on GitHub (pinned to fad1729dce)

Solutions

1. Upgrade Hibernate - several UnknownTableReferenceException fixes for filter + joined inheritance landed across 6.4-7.x
2. Add an explicit discriminator (@DiscriminatorColumn) to the JOINED hierarchy so filter pruning does not need to retain subclass joins
3. Rephrase the query to select the concrete subtype, or move the filter condition to a query restriction (WHERE clause) instead of @Filter
4. If it persists on the latest version, report a minimal reproducer to Hibernate (HHH)

try { results = query.getResultList(); } catch (UnknownTableReferenceException e) { /* filter + JOINED inheritance pruning failed on this Hibernate version: retry without the filter applied, or query the concrete subtype */ }

When it happens

Trigger: Enabling a @Filter/@FilterDef on a JOINED-inheritance entity (which by default has no discriminator column) combined with criteria/HQL that prune or reuse table groups: treat(), to-one join fetches to the hierarchy, entity graphs, or subselect fetching; historically also straight Hibernate defects in this pruning path.

Common situations: Soft-delete or multi-tenant filters on JOINED hierarchies; upgrading to Hibernate 6.4+/7.x where EntityNameUse-based pruning introduced regressions; queries with @Fetch(JOIN) or entity graphs targeting filtered hierarchies.

Related errors

• Discriminator formulas on joined inheritance hierarchies not
• Could not format discriminator value to SQL string
• optimistic-lock=all|dirty not supported for joined-subclass
• Encountered 'subclass table index' [%s] was outside expected
• Was unable to locate subclass table [%s] in 'subclassTableNa

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