{"record":{"id":"90ddce9fff6d4ed5","repo":"hibernate/hibernate-orm","slug":"could-not-locate-secondary-table-name","errorCode":null,"errorMessage":"Could not locate secondary Table : \" + name","messagePattern":"Could not locate secondary Table : \" \\+ name","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java","lineNumber":1228,"sourceCode":"\t\treturn table;\n\t}\n\n\t@Override\n\tpublic Join findSecondaryTable(String name) {\n\t\tfor ( int i = 0; i < joins.size(); i++ ) {\n\t\t\tfinal var join = joins.get( i );\n\t\t\tif ( join.getTable().getNameIdentifier().matches( name ) ) {\n\t\t\t\treturn join;\n\t\t\t}\n\t\t}\n\t\treturn null;\n\t}\n\n\t@Override\n\tpublic Join getSecondaryTable(String name) {\n\t\tfinal var secondaryTable = findSecondaryTable( name );\n\t\tif ( secondaryTable == null ) {\n\t\t\tthrow new MappingException( \"Could not locate secondary Table : \" + name );\n\t\t}\n\t\treturn secondaryTable;\n\t}\n\n\t@Override\n\tpublic IdentifiableTypeClass getSuperType() {\n\t\tfinal var superPersistentClass = getSuperclass();\n\t\tif ( superPersistentClass != null ) {\n\t\t\treturn superPersistentClass;\n\t\t}\n\t\treturn superMappedSuperclass;\n\t}\n\n\t@Override\n\tpublic List<IdentifiableTypeClass> getSubTypes() {\n\t\tthrow new UnsupportedOperationException( \"Not implemented yet\" );\n\t}\n","sourceCodeStart":1210,"sourceCodeEnd":1246,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java#L1210-L1246","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nString table = \"user_audits\"; // typo\nJoin join = rootClass.getSecondaryTable(table);\n\n// after\nString table = \"user_audit\";\nJoin join = rootClass.getSecondaryTable(table);","handlingStrategy":"validation","validationCode":"if (pc.findSecondaryTable(name) == null) {\n    // not a secondary table of this entity; the primary table is not considered here\n}","typeGuard":"static boolean isSecondaryTableOf(PersistentClass pc, String name) {\n    return pc.findSecondaryTable(name) != null;\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["hibernate","orm","secondary-table","table-lookup","mapping"],"backgroundTag":"unknown-table-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}