{"record":{"id":"9e248ca585279106","repo":"hibernate/hibernate-orm","slug":"result-set-mappings-can-only-be-used-with-native-s","errorCode":null,"errorMessage":"Result set mappings can only be used with native SQL queries","messagePattern":"Result set mappings can only be used with native SQL queries","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/SelectionQueryImpl.java","lineNumber":384,"sourceCode":"\tpublic <X> SelectionQueryImplementor<X> asSelectionQuery(EntityGraph<X> entityGraph) {\n\t\treturn asSelectionQuery( entityGraph, GraphSemantic.LOAD );\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic <X> SelectionQueryImplementor<X> asSelectionQuery(EntityGraph<X> entityGraph, GraphSemantic graphSemantic) {\n\t\treturn new SelectionQueryImpl<>(\n\t\t\t\tthis,\n\t\t\t\tentityGraph.getGraphedType().getJavaType(),\n\t\t\t\t(RootGraphImplementor<X>) entityGraph,\n\t\t\t\tgraphSemantic\n\t\t);\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic <S> SelectionQueryImplementor<S> withResultSetMapping(@Nonnull ResultSetMapping<S> mapping) {\n\t\tthrow new IllegalStateException( \"Result set mappings can only be used with native SQL queries\" );\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Options\n\n\t@Override\n\tpublic boolean isReadOnly() {\n\t\treturn queryOptions.isReadOnly() == null\n\t\t\t\t? session.isDefaultReadOnly()\n\t\t\t\t: queryOptions.isReadOnly();\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic SelectionQueryImplementor<R> setReadOnly(boolean readOnly) {\n\t\tqueryOptions.setReadOnly( readOnly );\n\t\treturn this;","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/SelectionQueryImpl.java#L366-L402","documentation":"A ResultSetMapping describes how SQL result columns map to Java values, which only makes sense for native SQL. SelectionQueryImpl (HQL/JPQL and criteria queries) implements withResultSetMapping by throwing IllegalStateException, because HQL selects already carry typed Sqm selections and no column mapping exists. Call it only on a NativeQuery.","triggerScenarios":"Calling withResultSetMapping(mapping) (or a wrapper like applyResultSetMapping) on a query produced by em.createQuery(hql) / session.createQuery(...) or from a CriteriaQuery - anything that is not a NativeQuery.","commonSituations":"Migrating @SqlResultSetMapping-style native queries toward HQL while keeping the mapping call; generic query-execution helpers that accept the common Query interface and unconditionally apply mappings.","solutions":["Use a native query: session.createNativeQuery(sql) / em.createNativeQuery(...) and apply the mapping there.","For HQL, project into a DTO ('select new ...') or Tuple instead of a result-set mapping.","In shared code, branch on NativeQuery before applying the mapping."],"exampleFix":"// before\nvar q = session.createQuery(\"select p from Person p\", Person.class); // HQL\nq.withResultSetMapping(mapping); // throws\n\n// after\nvar q = session.createNativeQuery(\"select * from person\", Person.class);\nq.withResultSetMapping(mapping); // NativeQuery supports result set mappings","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"static boolean supportsResultSetMapping(org.hibernate.query.Query<?> q) {\n    return q instanceof org.hibernate.query.NativeQuery;\n}","tryCatchPattern":null,"preventionTips":["Apply result set mappings only right after creating a native query.","For HQL projections use DTO constructor expressions or Tuple.","Branch shared execution helpers on NativeQuery before touching mappings."],"tags":["hibernate","resultset-mapping","native-query","selection-query","illegal-state"],"backgroundTag":"resultset-mapping-misuse","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}