{"record":{"id":"d865df5208767b61","repo":"gastownhall/beads","slug":"invalid-offset-an-offset-cannot-be-combined-with","errorCode":null,"errorMessage":"invalid offset: an offset cannot be combined with a display order, because the order is applied to the rows the query bounded and each page would be sorted for itself","messagePattern":"invalid offset: an offset cannot be combined with a display order, because the order is applied to the rows the query bounded and each page would be sorted for itself","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/workapi/query.go","lineNumber":76,"sourceCode":"//\n// It reads no configuration and touches no store, so both implementations share\n// it without supplying a config source.\nfunc BuildQueryPlan(in issueops.QueryRequest) (QueryPlan, error) {\n\texpression := strings.TrimSpace(in.Expression)\n\tif expression == \"\" {\n\t\treturn QueryPlan{}, invalidQueryExpression(\"an expression is required\")\n\t}\n\tlimit := LimitOr(in.Limit, DefaultQueryLimit)\n\tif limit < 0 {\n\t\treturn QueryPlan{}, fmt.Errorf(\"invalid limit %d: a query limit must be zero or greater; 0 means unlimited%.0w\",\n\t\t\tlimit, issueops.ErrValidation)\n\t}\n\tif in.Offset < 0 {\n\t\treturn QueryPlan{}, fmt.Errorf(\"invalid offset %d: a query offset must be zero or greater%.0w\",\n\t\t\tin.Offset, issueops.ErrValidation)\n\t}\n\tif in.Offset > 0 && in.SortBy != \"\" {\n\t\treturn QueryPlan{}, fmt.Errorf(\n\t\t\t\"invalid offset: an offset cannot be combined with a display order, because the order is applied to the rows the query bounded and each page would be sorted for itself%.0w\",\n\t\t\tissueops.ErrValidation)\n\t}\n\n\tnode, err := query.Parse(expression)\n\tif err != nil {\n\t\treturn QueryPlan{}, invalidQueryExpression(err.Error())\n\t}\n\tresult, err := query.NewEvaluator(time.Now()).Evaluate(node)\n\tif err != nil {\n\t\treturn QueryPlan{}, invalidQueryExpression(err.Error())\n\t}\n\n\tplan := QueryPlan{\n\t\tFilter:  result.Filter,\n\t\tLimit:   limit,\n\t\tOffset:  in.Offset,\n\t\tSortBy:  in.SortBy,","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/workapi/query.go#L58-L94","documentation":"BuildQueryPlan refuses a request that combines Offset > 0 with a SortBy display order. The reason is in the message: the display order applies to the bounded result rows, so each page would be sorted independently and pages would not compose into a global order. The error wraps issueops.ErrValidation.","triggerScenarios":"Calling BuildQueryPlan with both Offset > 0 and a non-empty in.SortBy — e.g. a client that paginates with offset while also asking for `sort: priority` display ordering.","commonSituations":"An API client adding both pagination and a sort dropdown; a UI that keeps the previous sort when the user advances to page 2; generated clients that always serialize sort and offset fields.","solutions":["Drop the offset and paginate by keyset/cursor when a display order is requested","Clear SortBy when using offset pagination (the query expression itself can express ordering)","Fetch all matching rows with the display order and slice client-side if the set is small"],"exampleFix":"// before\nreq := issueops.QueryRequest{Expression: \"status = open\", Offset: 20, SortBy: \"priority\"}\n// after\nreq := issueops.QueryRequest{Expression: \"status = open\", Offset: 20} // or use cursor pagination with SortBy","handlingStrategy":"validation","validationCode":"if req.Offset > 0 && req.SortBy != \"\" {\n\treturn errors.New(\"cannot combine offset with display order; use cursor pagination\")\n}","typeGuard":null,"tryCatchPattern":"plan, err := BuildQueryPlan(req)\nif err != nil && errors.Is(err, issueops.ErrValidation) && strings.Contains(err.Error(), \"display order\") {\n\t// drop SortBy or switch to cursor pagination and retry once\n}","preventionTips":["Choose one pagination model per endpoint: offset XOR display-order paging","Clear SortBy when the user pages with offsets","Express ordering inside the query expression when offset pagination is required"],"tags":["validation","query","pagination","sorting"],"backgroundTag":"offset-sort-conflict","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}