{"record":{"id":"39dd76c49d8142b0","repo":"gastownhall/beads","slug":"priority-must-be-between-0-and-4","errorCode":null,"errorMessage":"priority must be between 0 and 4","messagePattern":"priority must be between 0 and 4","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/query/evaluator.go","lineNumber":231,"sourceCode":"\tstatus := types.Status(strings.ToLower(comp.Value))\n\tif !status.IsValid() {\n\t\treturn fmt.Errorf(\"invalid status: %s\", comp.Value)\n\t}\n\tif comp.Op == OpEquals {\n\t\tfilter.Status = &status\n\t} else {\n\t\tfilter.ExcludeStatus = append(filter.ExcludeStatus, status)\n\t}\n\treturn nil\n}\n\nfunc (e *Evaluator) applyPriorityFilter(comp *ComparisonNode, filter *types.IssueFilter) error {\n\tpriority, err := strconv.Atoi(comp.Value)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"invalid priority value: %s\", comp.Value)\n\t}\n\tif priority < 0 || priority > 4 {\n\t\treturn fmt.Errorf(\"priority must be between 0 and 4\")\n\t}\n\n\tswitch comp.Op {\n\tcase OpEquals:\n\t\tfilter.Priority = &priority\n\tcase OpNotEquals:\n\t\t// For != we need predicate filtering\n\t\treturn fmt.Errorf(\"priority != requires predicate filtering\")\n\tcase OpLess:\n\t\t// priority < X means PriorityMax = X-1\n\t\tmax := priority - 1\n\t\tif max < 0 {\n\t\t\treturn fmt.Errorf(\"priority < %d matches nothing\", priority)\n\t\t}\n\t\tfilter.PriorityMax = &max\n\tcase OpLessEq:\n\t\tfilter.PriorityMax = &priority\n\tcase OpGreater:","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/query/evaluator.go#L213-L249","documentation":"Beads supports exactly five priority levels, 0 (critical) through 4 (backlog). applyPriorityFilter rejects any successfully parsed integer outside that range with this error. This keeps query filters aligned with the priority enum used throughout the issue store.","triggerScenarios":"Queries like `priority = 5`, `priority >= 10`, `priority < -1` — any parsed integer < 0 or > 4, regardless of operator.","commonSituations":"Porting queries from systems with larger priority ranges (Jira 1–5, GitHub labels); scripts that compute priorities arithmetically and overflow; users guessing that P5 or P10 exists.","solutions":["Clamp or validate the priority to 0–4 before building the query.","Map external priority scales into beads' 0–4 range (e.g. Jira P5 → beads 4).","To express \"any priority\", omit the priority clause entirely rather than using an out-of-range sentinel like 99."],"exampleFix":"// before\n\"priority <= 9\"\n// after (beads max is 4)\n\"priority <= 4\"\n// Go guard before parsing\nif p < 0 || p > 4 { return fmt.Errorf(\"priority must be 0-4\") }","handlingStrategy":"validation","validationCode":"func validatePriorityRange(p int) error {\n    if p < 0 || p > 4 {\n        return fmt.Errorf(\"priority %d out of range: beads supports 0-4\", p)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := e.applyComparison(comp, filter); err != nil {\n    if strings.Contains(err.Error(), \"priority must be between 0 and 4\") {\n        p := clamp(comp.Value, 0, 4) // retry with clamped value\n        return e.applyPriorityFilter(comp.WithValue(p), filter)\n    }\n    return err\n}","preventionTips":["Clamp external priority scales into 0-4 before query construction.","Omit the priority clause entirely when \"any priority\" is meant — never use out-of-range sentinels like 99.","Document beads' 0-4 scale wherever priorities are entered."],"tags":["query","priority","validation","beads"],"backgroundTag":"value-out-of-range","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}