What causes "Could not locate Table : " + name" in hibernate/hibernate-orm?

Declare the secondary table on the entity with @SecondaryTable or a join element in hbm.xml

hibernate/hibernate-orm · error · MappingException

Could not locate Table : " + name

Error message

Could not locate Table : " + name

What it means

A table lookup by name failed: getTable(name) checks the primary table and all secondary tables (joins) and throws when none matches. The name must match the table's name identifier, and catalog/schema qualifiers make mismatches possible. It typically fires while resolving column-to-table references such as @Column(table=...) during binding or constraint creation.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java:1208

	}

	@Override
	public Table findTable(String name) {
		if ( getTable().getName().equals( name ) ) {
			return getTable();
		}
		final var secondaryTable = findSecondaryTable( name );
		if ( secondaryTable != null ) {
			return secondaryTable.getTable();
		}
		return null;
	}

	@Override
	public Table getTable(String name) {
		final var table = findTable( name );
		if ( table == null ) {
			throw new MappingException( "Could not locate Table : " + name );
		}
		return table;
	}

	@Override
	public Join findSecondaryTable(String name) {
		for ( int i = 0; i < joins.size(); i++ ) {
			final var join = joins.get( i );
			if ( join.getTable().getNameIdentifier().matches( name ) ) {
				return join;
			}
		}
		return null;
	}

	@Override
	public Join getSecondaryTable(String name) {
		final var secondaryTable = findSecondaryTable( name );

View on GitHub (pinned to fad1729dce)

Solutions

Declare the secondary table on the entity with @SecondaryTable or a join element in hbm.xml
Make the referenced name match the declared table name exactly (case, catalog, schema)
Move the column back to the primary table if a secondary table was not intended

Example fix

// before
@Entity
@SecondaryTable(name = "user_audit")
@Column(name = "changed_at", table = "user_audits") // typo
private Instant changedAt;

// after
@Column(name = "changed_at", table = "user_audit")
private Instant changedAt;

Defensive patterns

Strategy: validation

Validate before calling

if (pc.findTable(tableName) == null) {
    // the entity does not map this table (primary or secondary); declare it or fix the name
}

Prevention

Declare every @SecondaryTable on the entity that places columns in it
Use constants for table names to avoid typos between @SecondaryTable and @Column(table=...)
Prefer @TableGenerator-style naming checks in a startup assertion

When it happens

Trigger: @Column(table = "AUDIT") on an entity that never declared @SecondaryTable(name = "AUDIT"); an hbm join element missing while a property table attribute references it; case or schema-qualified names that do not exactly match the declared table.

Common situations: Typos in secondary-table names; moving columns between tables during refactors; schemas where logical and physical names differ.

Related errors

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