hibernate/hibernate-orm · error · IllegalStateException

Was unable to locate subclass table [%s] in 'subclassTableNa

Error message

Was unable to locate subclass table [%s] in 'subclassTableNameClosure'

What it means

Same construction-time pass as the subclass table index check: after scanning subclassTableNameClosure for a table owned by a subclass, no entry matched, so Hibernate cannot associate subclass class names with that table. It means the table referenced by the subclass mapping is not part of the subclass table-name closure - the names disagree (quoting or case) or the closure was built without that join. SessionFactory boot fails with an IllegalStateException naming the table.

Source

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

			if ( subclassTableNameClosure[i].equals( tableName ) ) {
				found = true;
				final int index = i - coreTableSpan;
				if ( index < 0 || index >= mapping.length ) {
					throw new IllegalStateException(
							String.format(
									"Encountered 'subclass table index' [%s] was outside expected range ( [%s] < i < [%s] )",
									index,
									0,
									mapping.length
							)
					);
				}
				mapping[index] = toStringArray( classNames );
				break;
			}
		}
		if ( !found ) {
			throw new IllegalStateException(
					String.format(
							"Was unable to locate subclass table [%s] in 'subclassTableNameClosure'",
							tableName
					)
			);
		}
	}

	@Override
	public boolean needsDiscriminator() {
		return forceDiscriminator;
	}

	@Override
	public boolean isNullableTable(int j) {
		return isNullableTable[j];
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use one exact, consistently-quoted table name everywhere the table appears in the hierarchy
2. Check hibernate.globally_quoted_identifiers and your physical naming strategy for name rewrites
3. Upgrade Hibernate to the latest patch release (closure-building fixes landed across 6.x/7.x)
4. Simplify the hierarchy - drop joins temporarily - to isolate which mapping fragment introduces the unknown table

When it happens

Trigger: JOINED hierarchy where a subclass join table is quoted (backticks) in one mapping location and unquoted in another; globally-quoted identifiers (hibernate.globally_quoted_identifiers) interacting with explicit quotes; a physical naming strategy producing a different physical name than the @Table value; duplicate subclass mappings referencing the same table.

Common situations: Mixed hbm.xml and annotation mappings with inconsistent quoting; case-sensitive identifier databases (PostgreSQL, Oracle); migration from Hibernate 5 hbm join mappings; ImplicitNamingStrategy/PhysicalNamingStrategy overrides renamed tables after closure construction.

Related errors

• Discriminator formulas on joined inheritance hierarchies not
• optimistic-lock=all|dirty not supported for joined-subclass
• Encountered 'subclass table index' [%s] was outside expected
• Identifier property '" + getPath( holder, data ) + "' cannot
• Attribute '%s' of entity '%s' is mapped by association '%s'

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