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

Declare the @SecondaryTable on the class the reference is resolved against

hibernate/hibernate-orm · error · MappingException

Could not locate secondary Table : " + name

Error message

Could not locate secondary Table : " + name

What it means

Dedicated secondary-table lookup failed: getSecondaryTable(name) only scans the entity's joins (secondary tables) and throws when no join matches. Unlike getTable(), the primary table is not considered, so even a name matching the primary table throws here.

Source

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

		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 );
		if ( secondaryTable == null ) {
			throw new MappingException( "Could not locate secondary Table : " + name );
		}
		return secondaryTable;
	}

	@Override
	public IdentifiableTypeClass getSuperType() {
		final var superPersistentClass = getSuperclass();
		if ( superPersistentClass != null ) {
			return superPersistentClass;
		}
		return superMappedSuperclass;
	}

	@Override
	public List<IdentifiableTypeClass> getSubTypes() {
		throw new UnsupportedOperationException( "Not implemented yet" );
	}

View on GitHub (pinned to fad1729dce)

Solutions

Declare the @SecondaryTable on the class the reference is resolved against
Fix the name to match the declared secondary table exactly
Use findSecondaryTable() and handle null instead of getSecondaryTable() when absence is a normal case

Example fix

// before
String table = "user_audits"; // typo
Join join = rootClass.getSecondaryTable(table);

// after
String table = "user_audit";
Join join = rootClass.getSecondaryTable(table);

Defensive patterns

Strategy: validation

Validate before calling

if (pc.findSecondaryTable(name) == null) {
    // not a secondary table of this entity; the primary table is not considered here
}

Type guard

static boolean isSecondaryTableOf(PersistentClass pc, String name) {
    return pc.findSecondaryTable(name) != null;
}

Prevention

Use findSecondaryTable() with a null check when absence is a normal outcome
Keep secondary-table names in one place per entity instead of repeating string literals

When it happens

Trigger: Calling getSecondaryTable with the primary table's name; referencing a @SecondaryTable that is not declared on that entity (typo, declared on another class in the hierarchy); identifier comparison failing on catalog/schema-qualified names because matches() is exact.

Common situations: Custom integrations resolving secondary tables by name; renamed secondary tables during refactors; secondary tables declared on a different class of the hierarchy than the reference expects.

Related errors

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