hibernate/hibernate-orm · error · IllegalArgumentException

Unable to resolve TableMapping for selectable - %s

Error message

Unable to resolve TableMapping for selectable - %s

What it means

Before applying a mutation, UpdateCoordinatorStandard.physicalTableMappingForMutation resolves the dirty selectable's physical table via persister.physicalTableNameForMutation() and matches it against persister.getTableMappings(). IllegalArgumentException 'Unable to resolve TableMapping for selectable' means the selectable's owning table name matches none of the persister's tables - the attribute is being mutated through a persister that does not own its table, typically a mapping inconsistency.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/mutation/UpdateCoordinatorStandard.java:1829

		final var propertyLaziness = persister.getPropertyLaziness();
		for ( int dirtyField : dirtyFields ) {
			if ( propertyLaziness[dirtyField] ) {
				return true;
			}
		}
		return false;
	}

	public EntityTableMapping physicalTableMappingForMutation(
			EntityPersister persister, SelectableMapping selectableMapping) {
		final String tableNameForMutation = persister.physicalTableNameForMutation( selectableMapping );
		for ( var tableMapping : persister.getTableMappings() ) {
			if ( tableNameForMutation.equals( tableMapping.getTableName() ) ) {
				return tableMapping;
			}
		}

		throw new IllegalArgumentException( "Unable to resolve TableMapping for selectable - " + selectableMapping );
	}

	@Override
	public String toString() {
		return "UpdateCoordinatorStandard(" + entityPersister().getEntityName() + ")";
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Make every @Column(table=...) / <column table=...> value exactly match a @SecondaryTable or join name of the same entity
2. Verify the physical naming strategy output (case, quoting) for secondary tables matches the declared names
3. Mark columns owned by other tables insertable=false updatable=false so they never appear in mutations
4. Reduce to a minimal entity; if the mapping looks consistent, report it to Hibernate (HHH)

Example fix

// before: column references a table not owned by the entity
@Entity
@SecondaryTable(name = "user_details")
public class User {
    @Column(table = "user_detail", insertable = false, updatable = true) // typo -> unresolvable
    String bio;
}

// after: table attribute matches the declared secondary table
@Column(table = "user_details")
String bio;

// after Metadata build: every updatable column's table must be owned by its entity
for (PersistentClass pc : metadata.getEntityBindings()) {
    Set<String> owned = new HashSet<>();
    owned.add(pc.getRootTable().getName());
    pc.getJoinClosureIterator().forEachRemaining(j -> owned.add(j.getTable().getName()));
    pc.getPropertyClosureIterator().forEachRemaining(prop ->
        prop.getColumnIterator().forEachRemaining(col -> {
            String t = col.getValue().getTable().getName();
            if (!owned.contains(t) && col.isQuoted() || !owned.contains(t)) {
                // flag columns resolving to tables this entity does not own
            }
        }));
}

try { session.update(entity); } catch (IllegalArgumentException e) { if (e.getMessage().contains("resolve TableMapping")) { /* align @Column(table=...) with the entity's secondary tables */ } throw e; }

When it happens

Trigger: hbm.xml <column table="other"/> or @Column(table=...) pointing at a table not declared as @SecondaryTable/join on the same entity; secondary-table names mismatched by case or quoting (case-sensitive databases); custom types marking foreign-table columns dirty; edge inheritance paths mutating subclass-owned attributes through the wrong persister.

Common situations: Renaming a secondary table in one place but not everywhere; hand-edited hbm.xml join mappings; physical naming strategies rewriting secondary table names; PostgreSQL/Oracle case sensitivity around quoted identifiers.

Related errors

• Table [%s] contains logical column name [%s] referring to mu
• Table [%s] contains physical column name [%s] referred to by
• Column with logical name '%s' in table '%s' cannot be mapped
• Secondary table (<join/>) must explicitly name table or sub-
• Could not locate Table : " + name

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