{"record":{"id":"9771ae229c9cd66a","repo":"hibernate/hibernate-orm","slug":"given-subclass-table-number-is-outside-expected-ra","errorCode":null,"errorMessage":"Given subclass table number is outside expected range [%s] as defined by subclassTableNameClosure/subclassClosure","messagePattern":"Given subclass table number is outside expected range \\[(.+?)\\] as defined by subclassTableNameClosure/subclassClosure","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/persister/entity/JoinedSubclassEntityPersister.java","lineNumber":939,"sourceCode":"\t\tif ( treatAsDeclarations != null && !treatAsDeclarations.isEmpty() ) {\n\t\t\tfinal var inclusionSubclassNameClosure =\n\t\t\t\t\tgetSubclassNameClosureBySubclassTable( subclassTableNumber );\n\t\t\t// NOTE: we assume the entire hierarchy is joined-subclass here\n\t\t\tfor ( String subclassName : treatAsDeclarations ) {\n\t\t\t\tfor ( String inclusionSubclassName : inclusionSubclassNameClosure ) {\n\t\t\t\t\tif ( inclusionSubclassName.equals( subclassName ) ) {\n\t\t\t\t\t\treturn true;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn false;\n\t}\n\n\tprivate String[] getSubclassNameClosureBySubclassTable(int subclassTableNumber) {\n\t\tfinal int index = subclassTableNumber - getTableSpan();\n\t\tif ( index >= subclassNamesBySubclassTable.length ) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Given subclass table number is outside expected range [\" + (subclassNamesBySubclassTable.length -1)\n\t\t\t\t\t\t\t+ \"] as defined by subclassTableNameClosure/subclassClosure\"\n\t\t\t);\n\t\t}\n\t\treturn subclassNamesBySubclassTable[index];\n\t}\n\n\t@Override\n\tpublic String[] getConstraintOrderedTableNameClosure() {\n\t\treturn constraintOrderedTableNames;\n\t}\n\n\t@Override\n\tpublic String[][] getConstraintOrderedTableKeyColumnClosure() {\n\t\treturn constraintOrderedKeyColumnNames;\n\t}\n\n\t@Override","sourceCodeStart":921,"sourceCodeEnd":957,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/persister/entity/JoinedSubclassEntityPersister.java#L921-L957","documentation":"getSubclassNameClosureBySubclassTable translates a subclass table number into the class names mapped to that table; it is used when Hibernate prunes/polymorphically restricts a TableGroup for a JOINED hierarchy (filters, treat(), entity-name uses). IllegalArgumentException indicates the passed table number, minus getTableSpan(), indexes past the end of subclassNamesBySubclassTable - a caller used a table number beyond the known subclass tables, normally an internal defect or a query path the pruning code did not expect.","triggerScenarios":"Polymorphic criteria/HQL with treat() over a JOINED hierarchy; @Filter/@FilterDef applying entity-name-use pruning; loading through @Polymorphic/interface references; any path where the table-span arithmetic at query time diverges from the array built at construction time.","commonSituations":"treat(as: SubType) in HQL/Criteria on JOINED inheritance; soft-delete or tenant filters on joined hierarchies; upgrading between Hibernate 6.4/6.6/7.x where EntityNameUse pruning internals changed.","solutions":["Upgrade Hibernate - pruning arithmetic for joined-subclass persisters has had multiple fixes","Rewrite the query to select the concrete subtype directly instead of using treat()/polymorphic pruning","Temporarily remove filters/treat() to confirm they trigger the path","If it reproduces on the latest version, file a Hibernate (HHH) issue with the query and mapping"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { results = query.getResultList(); } catch (IllegalArgumentException e) { /* treat()/filter pruning over JOINED hierarchy unsupported on this version: fall back to selecting the concrete subtype */ }","preventionTips":["Prefer selecting concrete subtypes over treat() on JOINED hierarchies","Keep Hibernate patched - pruning arithmetic fixes land regularly","Add query-layer tests for every polymorphic query with filters or treat()"],"tags":["hibernate","orm","joined-inheritance","criteria","treat","pruning"],"backgroundTag":"joined-inheritance-table-mapping-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}