{"record":{"id":"3ddf3d606ec96da0","repo":"hibernate/hibernate-orm","slug":"cannot-order-by-element-element-the-first","errorCode":null,"errorMessage":"Cannot order by element \" + element + \" (the first select item is element 1)","messagePattern":"Cannot order by element \" \\+ element \\+ \" \\(the first select item is element 1\\)","errorType":"exception","errorClass":"IllegalQueryOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmUtil.java","lineNumber":952,"sourceCode":"\t\t\t\t\twhile ( tokens.hasMoreTokens() ) {\n\t\t\t\t\t\tpath = path.get( tokens.nextToken() );\n\t\t\t\t\t}\n\t\t\t\t\treturn builder.sort( path, order.direction(), order.nullPrecedence(), !order.caseSensitive() );\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\tthrow new IllegalQueryOperationException(\"Select item was not an entity type\");\n\t\t\t\t}\n\t\t\t}\n\t\t\telse {\n\t\t\t\tthrow new IllegalQueryOperationException(\"Query has multiple items in the select list\");\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate static SqmSelectableNode<?> selectedNode(AbstractSqmSelectQuery<?> sqm, Order<?> order) {\n\t\tfinal int element = order.element();\n\t\tif ( element < 1) {\n\t\t\tthrow new IllegalQueryOperationException(\"Cannot order by element \" + element\n\t\t\t\t\t+ \" (the first select item is element 1)\");\n\t\t}\n\t\tfinal var querySpec = sqm.getQuerySpec();\n\t\tfinal var selectionItems = querySpec.getSelectClause().getSelectionItems();\n\t\tfinal int items = selectionItems.size();\n\t\tif ( items == 0 && element == 1 ) {\n\t\t\tif ( order.entityClass() == null || querySpec.getRootList().size() > 1 ) {\n\t\t\t\tthrow new IllegalQueryOperationException(\"Cannot order by element \" + element\n\t\t\t\t\t\t+ \" (there is no select list)\");\n\t\t\t}\n\t\t\telse {\n\t\t\t\treturn querySpec.getRootList().get(0);\n\t\t\t}\n\t\t}\n\t\telse if ( element > items ) {\n\t\t\tthrow new IllegalQueryOperationException( \"Cannot order by element \" + element\n\t\t\t\t\t+ \" (there are only \" + items + \" select items)\");\n\t\t}","sourceCodeStart":934,"sourceCodeEnd":970,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmUtil.java#L934-L970","documentation":"Thrown as IllegalQueryOperationException by SqmUtil.selectedNode when Order.element() is less than 1. Select-list element positions used for ordering are 1-based: element 1 is the first select item. An Order built with element 0 or a negative number (or a default like -1 leaking from a record that never set a real position) is invalid before anything else is checked.","triggerScenarios":"Order.by(0, SortDirection.ASCENDING) or Order.by(-1, ...); mapping a 0-based sort-column index from a UI/API (DataTables, GraphQL order spec) straight into Order.by(index) without adding 1; a NamedAttributeOrder whose element() sentinel (-1) is passed through because no attribute name was set either.","commonSituations":"Frontend grid sorting sends 0-based column indexes; order specifications deserialized from JSON where the index field defaults to 0; glue code between a 0-based spec and Hibernate's 1-based element model.","solutions":["Use 1-based element positions: the first select item is element 1","Convert external 0-based indexes: Order.by(externalIndex + 1, direction)","If the order spec may be unset, skip addOrder when the index is not a positive number","Prefer entity-anchored Order.asc(Class, attributeName) when you know the attribute name"],"exampleFix":"// before (uiColumnIndex is 0-based)\nquery.addOrder(Order.by(uiColumnIndex, ascending ? SortDirection.ASCENDING : SortDirection.DESCENDING));\n// after\nquery.addOrder(Order.by(uiColumnIndex + 1, ascending ? SortDirection.ASCENDING : SortDirection.DESCENDING));","handlingStrategy":"validation","validationCode":"static int toHibernateElementIndex(int zeroBasedIndex) {\n    if (zeroBasedIndex < 0) {\n        throw new IllegalArgumentException(\"Column index must be >= 0 (0-based): \" + zeroBasedIndex);\n    }\n    return zeroBasedIndex + 1; // Hibernate select elements are 1-based\n}","typeGuard":null,"tryCatchPattern":"try {\n    query.addOrder(Order.by(element, direction)).getResultList();\n} catch (IllegalQueryOperationException e) {\n    if (element < 1) throw new IllegalArgumentException(\"Sort element must be >= 1, got \" + element, e);\n    throw e;\n}","preventionTips":["Document and test that Hibernate select elements are 1-based","Convert UI/API 0-based column indexes at the boundary (+1)","Reject order specs with non-positive element values during deserialization"],"tags":["hibernate","order-by","off-by-one","query-api"],"backgroundTag":"invalid-order-by-clause","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}