{"record":{"id":"b9da0cd8ac8216f8","repo":"hibernate/hibernate-orm","slug":"couldn-t-find-table-reference","errorCode":null,"errorMessage":"Couldn't find table reference","messagePattern":"Couldn't find table reference","errorType":"exception","errorClass":"UnknownTableReferenceException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/persister/entity/JoinedSubclassEntityPersister.java","lineNumber":1341,"sourceCode":"\t\t\t\t\tclassOrSuperclassTables.add( subclassTableNames[i] );\n\t\t\t\t}\n\t\t\t}\n\t\t\tif ( tablesToInnerJoin.isEmpty() ) {\n\t\t\t\ttablesToInnerJoin.addAll( classOrSuperclassTables );\n\t\t\t}\n\t\t\telse {\n\t\t\t\ttablesToInnerJoin.retainAll( classOrSuperclassTables );\n\t\t\t}\n\t\t\tif ( useKind == EntityNameUse.UseKind.FILTER && explicitDiscriminatorColumnName == null ) {\n\t\t\t\t// If there is no discriminator column,\n\t\t\t\t// we must retain all joins to subclass tables to be able to discriminate the rows\n\t\t\t\tfor ( int i = 0; i < subclassTableNames.length; i++ ) {\n\t\t\t\t\tif ( !persister.isClassOrSuperclassTable[i] ) {\n\t\t\t\t\t\tfinal String subclassTableName = subclassTableNames[i];\n\t\t\t\t\t\tfinal var mainTableReference =\n\t\t\t\t\t\t\t\ttableGroup.getTableReference( null, subclassTableName, false );\n\t\t\t\t\t\tif ( mainTableReference == null ) {\n\t\t\t\t\t\t\tthrow new UnknownTableReferenceException(\n\t\t\t\t\t\t\t\t\tsubclassTableName,\n\t\t\t\t\t\t\t\t\t\"Couldn't find table reference\"\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tretainedTableReferences.add( mainTableReference );\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t@Override\n\tpublic EntityIdentifierMapping getIdentifierMappingForJoin() {\n\t\t// If the joined subclass has a physical discriminator and has subtypes\n\t\t// we must use the root table identifier mapping for joining to allow table group elimination to work\n\t\treturn isPhysicalDiscriminator() && !getSubMappingTypes().isEmpty()\n\t\t\t\t? getRootEntityDescriptor().getIdentifierMapping()\n\t\t\t\t: super.getIdentifierMappingForJoin();","sourceCodeStart":1323,"sourceCodeEnd":1359,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/persister/entity/JoinedSubclassEntityPersister.java#L1323-L1359","documentation":"When a filter applies to a JOINED-inheritance hierarchy that has no explicit discriminator, Hibernate must keep every subclass-table join in the SQL to be able to tell rows apart. pruneForSubclasses looks up each subclass table's TableReference in the current TableGroup; UnknownTableReferenceException('Couldn't find table reference') means the TableGroup was built without that join, so the filter logic cannot proceed. Most often hit in query paths that build partial table groups (treat, restricted fetches) combined with @Filter.","triggerScenarios":"Enabling a @Filter/@FilterDef on a JOINED-inheritance entity (which by default has no discriminator column) combined with criteria/HQL that prune or reuse table groups: treat(), to-one join fetches to the hierarchy, entity graphs, or subselect fetching; historically also straight Hibernate defects in this pruning path.","commonSituations":"Soft-delete or multi-tenant filters on JOINED hierarchies; upgrading to Hibernate 6.4+/7.x where EntityNameUse-based pruning introduced regressions; queries with @Fetch(JOIN) or entity graphs targeting filtered hierarchies.","solutions":["Upgrade Hibernate - several UnknownTableReferenceException fixes for filter + joined inheritance landed across 6.4-7.x","Add an explicit discriminator (@DiscriminatorColumn) to the JOINED hierarchy so filter pruning does not need to retain subclass joins","Rephrase the query to select the concrete subtype, or move the filter condition to a query restriction (WHERE clause) instead of @Filter","If it persists on the latest version, report a minimal reproducer to Hibernate (HHH)"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { results = query.getResultList(); } catch (UnknownTableReferenceException e) { /* filter + JOINED inheritance pruning failed on this Hibernate version: retry without the filter applied, or query the concrete subtype */ }","preventionTips":["Add an explicit @DiscriminatorColumn to JOINED hierarchies that carry @Filter definitions","Track Hibernate release notes for UnknownTableReferenceException fixes and keep the version patched","Test each filter against every query shape that loads the hierarchy (treat, join fetch, entity graphs)"],"tags":["hibernate","orm","filters","joined-inheritance","table-group","unknown-table-reference"],"backgroundTag":"unknown-table-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}