hibernate/hibernate-orm · error · IllegalArgumentException

Table-expression (%s) did not match mutating table name - %s

Error message

Table-expression (%s) did not match mutating table name - %s

What it means

A mutation targets exactly one physical table. MutatingTableReference.resolveTableReference(navigablePath, tableExpression) returns 'this' when tableExpression equals the mutating table's name and throws IllegalArgumentException otherwise. The reference models a single table, so it cannot resolve secondary tables, join tables, or any other table expression.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/sql/model/ast/MutatingTableReference.java:70

	@Override
	public void accept(SqlAstWalker sqlTreeWalker) {
		throw new UnsupportedOperationException( "Mutating table reference should be handled by the statement visitation" );
	}

	@Override
	public Boolean visitAffectedTableNames(Function<String, Boolean> nameCollector) {
		return nameCollector.apply( getTableName() );
	}

	@Override
	public TableReference resolveTableReference(
			NavigablePath navigablePath,
			String tableExpression) {
		if ( getTableName().equals( tableExpression ) ) {
			return this;
		}

		throw new IllegalArgumentException(
				String.format(
						Locale.ROOT,
						"Table-expression (%s) did not match mutating table name - %s",
						tableExpression,
						getTableName()
				)
		);
	}

	@Override
	public TableReference resolveTableReference(
			NavigablePath navigablePath,
			ValuedModelPart modelPart,
			String tableExpression) {
		if ( getTableName().equals( tableExpression ) ) {
			return this;
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Guard the call: only resolve when mutatingTableReference.getTableName().equals(tableExpression)
2. Use the null-safe getTableReference(navigablePath, tableExpression, boolean) which returns null instead of throwing
3. Resolve each column against the TableReference of the table it is actually mapped to (via the mutation statement), not a single mutating reference
4. Fix the mapping so selectables of the mutated table use that table's expression

Example fix

// before
TableReference ref = mutatingTableReference.resolveTableReference( path, tableExpression ); // throws when mismatched

// after
TableReference ref = mutatingTableReference.getTableName().equals( tableExpression )
        ? mutatingTableReference
        : mutationStatement.resolveTableReference( path, tableExpression );

TableReference ref = mutatingTableReference.getTableName().equals( tableExpression )
        ? mutatingTableReference
        : null; // or resolve via the mutation statement

boolean canResolve(MutatingTableReference ref, String tableExpression) {
    return ref.getTableName().equals( tableExpression );
}

When it happens

Trigger: Mutation AST building that resolves a selectable's table expression against the mutating reference when the selectable is actually mapped to a different table - secondary tables (@SecondaryTable), joined-inheritance parent/child tables, @JoinTable mappings - or to a formula/derived expression.

Common situations: Mapping errors where a mutated table's column is declared with a different table expression; custom mutation builders resolving columns by table name; inheritance mappings assuming all columns belong to the mutated table.

Related errors

• Fetch clause may not be null
• Mutating table reference should be handled by the statement
• Property not among declared properties: " + property.getName
• Unable to resolve TableMapping for selectable - %s
• Could not find table group for: %s

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