{"record":{"id":"efd5ed9954502a67","repo":"gastownhall/beads","slug":"cannot-determine-linear-team-for-issue-s","errorCode":null,"errorMessage":"cannot determine Linear team for issue %s","messagePattern":"cannot determine Linear team for issue (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/tracker.go","lineNumber":243,"sourceCode":"\t\t}\n\t\tti := linearToTrackerIssue(created)\n\t\treturn &ti, nil\n\t}\n\n\tcreated, err := client.CreateIssue(ctx, issue.Title, description, priority, stateID, labelIDs)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tti := linearToTrackerIssue(created)\n\treturn &ti, nil\n}\n\nfunc (t *Tracker) UpdateIssue(ctx context.Context, externalID string, issue *types.Issue) (*tracker.TrackerIssue, error) {\n\t// Route to the correct team's client based on the external ID.\n\tclient := t.clientForExternalID(ctx, externalID)\n\tif client == nil {\n\t\treturn nil, fmt.Errorf(\"cannot determine Linear team for issue %s\", externalID)\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\t_, 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\tmapper := &linearFieldMapper{config: t.config, labelCache: labelCache}\n\tupdates := mapper.IssueToTracker(issue)\n\n\t// Resolve and include state so status changes are pushed to Linear.\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}","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/tracker.go#L225-L261","documentation":"Returned by Tracker.UpdateIssue when clientForExternalID cannot determine which Linear team a previously-synced issue belongs to, based on its external ID. The Linear client is per-team, so without a team mapping the update cannot be routed and is aborted.","triggerScenarios":"Tracker.UpdateIssue called with an externalID that does not correspond to any configured team (malformed/foreign external ID, or the team that owned the issue was removed from t.teamIDs config).","commonSituations":"Issues synced under an older multi-team config whose identifier format changed; stale external IDs after reconfiguring Linear teams; copying issues between databases; externalID pointing at a Linear team no longer listed in beads config.","solutions":["Confirm the externalID actually came from this tracker (a Linear issue identifier) and matches the current config","Re-add the missing Linear team to the tracker's team configuration so clientForExternalID can route the ID","Re-fetch/re-sync the issue to obtain a fresh, correctly-formatted external ID","Fall back to CreateIssue for the issue if it genuinely has no Linear counterpart"],"exampleFix":"// before\ntracker.UpdateIssue(ctx, \"ENG-9999\", issue) // team ENG not configured\n// after\ntracker.UpdateIssue(ctx, \"BEADS-1234\", issue) // externalID from a configured team","handlingStrategy":"validation","validationCode":"// Only update issues whose external ID was produced by this tracker for a configured team\nif !strings.Contains(externalID, primaryTeamKeyPrefix) && !knownTeamExternalID(externalID) {\n    return fmt.Errorf(\"external ID %q does not belong to any configured Linear team\", externalID)\n}","typeGuard":"func knownExternalID(id string) bool {\n    team, _, ok := splitLinearExternalID(id)\n    return ok && configuredTeams[team]\n}","tryCatchPattern":"updated, err := tracker.UpdateIssue(ctx, externalID, issue)\nif err != nil && strings.Contains(err.Error(), \"cannot determine Linear team\") {\n    // fall back to creating a fresh Linear issue instead\n    updated, err = tracker.CreateIssue(ctx, issue)\n}","preventionTips":["Always store external IDs exactly as returned by the tracker","Keep team config stable; re-sync after adding/removing Linear teams","Purge or re-map stale external IDs after team reconfiguration","Log the team routing decision when persisting external IDs"],"tags":["linear","routing","multi-team","configuration"],"backgroundTag":"linear-team-not-found-for-external-id","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}