{"record":{"id":"c7fbbb84661ec852","repo":"hibernate/hibernate-orm","slug":"table-expression-s-did-not-match-mutating-table","errorCode":null,"errorMessage":"Table-expression (%s) did not match mutating table name - %s","messagePattern":"Table-expression \\((.+?)\\) did not match mutating table name - (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/sql/model/ast/MutatingTableReference.java","lineNumber":70,"sourceCode":"\t@Override\n\tpublic void accept(SqlAstWalker sqlTreeWalker) {\n\t\tthrow new UnsupportedOperationException( \"Mutating table reference should be handled by the statement visitation\" );\n\t}\n\n\t@Override\n\tpublic Boolean visitAffectedTableNames(Function<String, Boolean> nameCollector) {\n\t\treturn nameCollector.apply( getTableName() );\n\t}\n\n\t@Override\n\tpublic TableReference resolveTableReference(\n\t\t\tNavigablePath navigablePath,\n\t\t\tString tableExpression) {\n\t\tif ( getTableName().equals( tableExpression ) ) {\n\t\t\treturn this;\n\t\t}\n\n\t\tthrow new IllegalArgumentException(\n\t\t\t\tString.format(\n\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\"Table-expression (%s) did not match mutating table name - %s\",\n\t\t\t\t\t\ttableExpression,\n\t\t\t\t\t\tgetTableName()\n\t\t\t\t)\n\t\t);\n\t}\n\n\t@Override\n\tpublic TableReference resolveTableReference(\n\t\t\tNavigablePath navigablePath,\n\t\t\tValuedModelPart modelPart,\n\t\t\tString tableExpression) {\n\t\tif ( getTableName().equals( tableExpression ) ) {\n\t\t\treturn this;\n\t\t}\n","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/sql/model/ast/MutatingTableReference.java#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Guard the call: only resolve when mutatingTableReference.getTableName().equals(tableExpression)","Use the null-safe getTableReference(navigablePath, tableExpression, boolean) which returns null instead of throwing","Resolve each column against the TableReference of the table it is actually mapped to (via the mutation statement), not a single mutating reference","Fix the mapping so selectables of the mutated table use that table's expression"],"exampleFix":"// before\nTableReference ref = mutatingTableReference.resolveTableReference( path, tableExpression ); // throws when mismatched\n\n// after\nTableReference ref = mutatingTableReference.getTableName().equals( tableExpression )\n        ? mutatingTableReference\n        : mutationStatement.resolveTableReference( path, tableExpression );","handlingStrategy":"validation","validationCode":"TableReference ref = mutatingTableReference.getTableName().equals( tableExpression )\n        ? mutatingTableReference\n        : null; // or resolve via the mutation statement","typeGuard":"boolean canResolve(MutatingTableReference ref, String tableExpression) {\n    return ref.getTableName().equals( tableExpression );\n}","tryCatchPattern":null,"preventionTips":["Compare getTableName() with the table expression before calling resolveTableReference","Use the null-safe getTableReference(...) variant in generic code","Resolve each column through the table it is mapped to, especially with secondary/joined tables"],"tags":["hibernate","orm","sql-ast","mutation","table-resolution","illegal-argument"],"backgroundTag":"unresolved-table-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}