{"record":{"id":"bf7b20217e2700cc","repo":"hibernate/hibernate-orm","slug":"the-jpa-specification-does-not-support-subqueries-bf7b20","errorCode":null,"errorMessage":"The JPA specification does not support subqueries having multiple select items. Please disable the JPA query compliance if you want to use this feature.","messagePattern":"The JPA specification does not support subqueries having multiple select items\\. Please disable the JPA query compliance if you want to use this feature\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/select/SqmSubQuery.java","lineNumber":493,"sourceCode":"\t\t}\n\t\tgetQueryPart().setOrderByClause( sqmOrderByClause );\n\t\treturn this;\n\t}\n\n\t@Override\n\tpublic JpaSubQuery<T> orderBy(List<Order> orders) {\n\t\tvalidateComplianceOrderBy();\n\t\tfinal SqmOrderByClause sqmOrderByClause = new SqmOrderByClause( orders.size() );\n\t\tfor ( Order order : orders ) {\n\t\t\tsqmOrderByClause.addSortSpecification( (SqmSortSpecification) order );\n\t\t}\n\t\tgetQueryPart().setOrderByClause( sqmOrderByClause );\n\t\treturn this;\n\t}\n\n\tprivate void validateComplianceMultiselect() {\n\t\tif ( nodeBuilder().isJpaQueryComplianceEnabled() ) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\"The JPA specification does not support subqueries having multiple select items. \" +\n\t\t\t\t\t\t\t\"Please disable the JPA query compliance if you want to use this feature.\" );\n\t\t}\n\t}\n\n\tprivate void validateComplianceOrderBy() {\n\t\tif ( nodeBuilder().isJpaQueryComplianceEnabled() ) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\"The JPA specification does not support subqueries having an order by clause. \" +\n\t\t\t\t\t\t\t\"Please disable the JPA query compliance if you want to use this feature.\" );\n\t\t}\n\t}\n\n\tprivate void validateComplianceFetchOffset() {\n\t\tif ( nodeBuilder().isJpaQueryComplianceEnabled() ) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\"The JPA specification does not support subqueries having a fetch or offset clause. \" +\n\t\t\t\t\t\t\t\"Please disable the JPA query compliance if you want to use this feature.\" );","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/select/SqmSubQuery.java#L475-L511","documentation":"With hibernate.jpa.compliance.query=true Hibernate enforces strict JPA semantics, and the JPA specification only allows a single select item in a subquery. Every multiselect(List) call on a subquery runs validateComplianceMultiselect(), which throws IllegalStateException when compliance is on, regardless of whether you actually passed multiple items — the JPA API itself does not permit the call on a subquery.","triggerScenarios":"Setting hibernate.jpa.compliance.query=true (or spring.jpa.properties.hibernate.jpa.compliance.query=true, or enabling a global JpaCompliance setting) and then calling subquery.multiselect(list) or subquery.multiselect(item1, item2).","commonSituations":"Teams turning on full JPA compliance for certification or strictness after previously using Hibernate-specific multi-column subqueries; upgrading apps where compliance defaults were reviewed; shared codebases where one module enables compliance and another uses extended subquery features.","solutions":["Use a single select item on the subquery: subquery.select(oneExpression), selecting one column or an aggregate of the tuple","Set hibernate.jpa.compliance.query=false if the Hibernate-specific multi-item subquery is intentional","Move the multi-item projection out of the subquery: use a CTE (with(...)) or a derived table in the outer query"],"exampleFix":"// before (with hibernate.jpa.compliance.query=true)\nsub.multiselect(root.get(\"id\"), root.get(\"total\")); // IllegalStateException\n\n// after\nsub.select(cb.tuple(root.get(\"id\"), root.get(\"total\"))); // still multi-item — instead:\nsub.select(root.get(\"id\")); // single item, JPA-compliant","handlingStrategy":"validation","validationCode":"if (((SqmCriteriaNodeBuilder) cb).isJpaQueryComplianceEnabled()) {\n    sub.select(singleExpression); // JPA allows only one item\n} else {\n    sub.multiselect(items);\n}","typeGuard":null,"tryCatchPattern":"try { sub.multiselect(items); } catch (IllegalStateException e) { if (e.getMessage().contains(\"multiple select items\")) { sub.select(items.get(0)); } else throw e; }","preventionTips":["Document hibernate.jpa.compliance.query=true in the project config and grep for multiselect on subqueries when enabling it","Keep subqueries single-item by design; put multi-value projections in the outer query or a CTE","Add a config-driven integration test that runs your query set under compliance=true"],"tags":["hibernate","jpa-compliance","configuration","subquery","criteria-api"],"backgroundTag":"jpa-query-compliance","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}