{"record":{"id":"900a308656cb85ef","repo":"gastownhall/beads","slug":"finding-state-for-status-s-w","errorCode":null,"errorMessage":"finding state for status %s: %w","messagePattern":"finding state for status (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/tracker.go","lineNumber":195,"sourceCode":"\t\tif li != nil {\n\t\t\tti := linearToTrackerIssue(li)\n\t\t\treturn &ti, nil\n\t\t}\n\t}\n\treturn nil, nil\n}\n\nfunc (t *Tracker) CreateIssue(ctx context.Context, issue *types.Issue) (*tracker.TrackerIssue, error) {\n\tclient := t.primaryClient()\n\tif client == nil {\n\t\treturn nil, fmt.Errorf(\"no Linear client available\")\n\t}\n\n\tpriority := PriorityToLinear(issue.Priority, t.config)\n\n\tstateID, err := t.findStateID(ctx, client, issue.Status)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"finding state for status %s: %w\", issue.Status, err)\n\t}\n\n\tlabelCache, err := BuildLabelCache(ctx, client)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"loading team labels: %w\", err)\n\t}\n\tlabelIDs, unknown := ResolveLabelIDs(issue, labelCache, t.config)\n\tfor _, name := range unknown {\n\t\tfmt.Fprintf(os.Stderr, \"linear: bead %s: label %q not found on Linear team (skipped)\\n\", issue.ID, name)\n\t}\n\n\t// Use issue.Description as-is: the sync engine's FormatDescription hook\n\t// (BuildLinearDescription) has already merged AcceptanceCriteria/Design/Notes\n\t// into the description before calling CreateIssue. Calling BuildLinearDescription\n\t// here a second time would duplicate those sections for issues with structured fields.\n\tdescription := issue.Description\n\n\t// Use idempotent creation when we have enough bead metadata to generate","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/tracker.go#L177-L213","documentation":"This error is returned by Tracker.CreateIssue when it cannot resolve the Linear workflow state ID for the beads issue's status. findStateID builds a state cache via the Linear API and then maps the beads status to a state; any failure fetching states or resolving the mapping is wrapped with \"finding state for status %s: %w\". It blocks issue creation because Linear requires a valid stateId for new issues.","triggerScenarios":"Calling Tracker.CreateIssue with an issue whose Status has no matching Linear workflow state in the target team (e.g. an unrecognized custom status), or when the GraphQL query to list workflow states fails (network error, expired/invalid API key, rate limit).","commonSituations":"Beads config maps a status to a Linear state name that was renamed or deleted on the Linear side; missing or stale LINEAR_API_KEY; team mismatch (issue routed to a team whose states were not configured); network outage or Linear API rate limiting.","solutions":["Verify the status-to-state mapping in your beads Linear config matches actual Linear workflow state names for the target team","Check that your Linear API key is valid, not expired, and has access to the target team's workflow states","Run with debug logging to see the underlying wrapped error from BuildStateCache (network vs. resolution)","Test the Linear GraphQL API connectivity directly (curl the endpoint) to rule out network/proxy issues"],"exampleFix":"// before\nissue.Status = types.Status(\"in-progress\") // not a beads-canonical status\n// after\nissue.Status = types.StatusInProgress // canonical beads status that maps cleanly via config","handlingStrategy":"validation","validationCode":"if issue.Status != types.StatusOpen && issue.Status != types.StatusInProgress && issue.Status != types.StatusClosed && issue.Status != types.StatusBlocked {\n    return fmt.Errorf(\"unsupported status %q for Linear sync\", issue.Status)\n}","typeGuard":"func isSyncableStatus(s types.Status) bool {\n    switch s {\n    case types.StatusOpen, types.StatusInProgress, types.StatusClosed, types.StatusBlocked:\n        return true\n    }\n    return false\n}","tryCatchPattern":"created, err := tracker.CreateIssue(ctx, issue)\nif err != nil {\n    var stateErr *StateResolutionError\n    if errors.As(err, nil) || strings.Contains(err.Error(), \"finding state for status\") {\n        // log and defer this issue; do not abort the whole sync\n    }\n    return err\n}","preventionTips":["Keep the status→state mapping config in sync with Linear workflow state names","Use canonical beads statuses rather than free-form status strings","Validate credentials with a cheap API call before running syncs","Alert on Linear state renames in the workspace"],"tags":["linear","state-mapping","api","sync"],"backgroundTag":"linear-workflow-state-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}