{"record":{"id":"5ed0aaffa8397c7e","repo":"gastownhall/beads","slug":"loading-team-labels-w","errorCode":null,"errorMessage":"loading team labels: %w","messagePattern":"loading team labels: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/tracker.go","lineNumber":200,"sourceCode":"\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\n\t// a stable marker. This prevents duplicate Linear issues when sync is\n\t// interrupted between the API create call and the local external_ref\n\t// write-back.\n\tif issue.ID != \"\" && issue.CreatedBy != \"\" {\n\t\tmarker := GenerateIdempotencyMarker(issue.ID, issue.CreatedBy, issue.CreatedAt.UnixNano())","sourceCodeStart":182,"sourceCodeEnd":218,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/tracker.go#L182-L218","documentation":"Returned by Tracker.CreateIssue when BuildLabelCache fails to fetch the target Linear team's labels via the GraphQL API. The label cache is needed to translate beads labels into Linear label IDs before creating the issue, so a fetch failure aborts creation.","triggerScenarios":"Tracker.CreateIssue called when the Linear labels query fails: invalid or expired API key, network error, rate limiting, or the token lacking scope to read team labels.","commonSituations":"Rotated Linear API key not updated in env/config; OAuth token missing label read scope; corporate proxy blocking Linear API; transient Linear API outage during sync.","solutions":["Check the LINEAR_API_KEY / OAuth credentials are valid and can read team labels","Retry the operation — label-cache fetch failures are often transient (rate limits, network blips)","Verify the token's scopes include reading issue labels for the team","Inspect the wrapped error returned in the %w chain for the concrete cause"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight: verify the API key can read labels\nclient := linear.NewClient(apiKey)\nif _, err := client.ListLabels(ctx); err != nil {\n    return fmt.Errorf(\"linear credentials/labels check failed: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"created, err := tracker.CreateIssue(ctx, issue)\nif err != nil && strings.Contains(err.Error(), \"loading team labels\") {\n    if retriable(err) {\n        time.Sleep(backoff)\n        created, err = tracker.CreateIssue(ctx, issue)\n    }\n}","preventionTips":["Rotate API keys through a secret manager and update config promptly","Grant the token label-read scope for all synced teams","Use exponential backoff around sync operations","Monitor Linear API status/uptime during sync windows"],"tags":["linear","labels","api","network"],"backgroundTag":"linear-api-fetch-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}