{"record":{"id":"55a7c9be23044a07","repo":"gastownhall/beads","slug":"failed-to-fetch-team-states-w","errorCode":null,"errorMessage":"failed to fetch team states: %w","messagePattern":"failed to fetch team states: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/client.go","lineNumber":645,"sourceCode":"\t\t\t\t\t\tid\n\t\t\t\t\t\tname\n\t\t\t\t\t\ttype\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t`\n\n\treq := &GraphQLRequest{\n\t\tQuery: query,\n\t\tVariables: map[string]interface{}{\n\t\t\t\"teamId\": c.TeamID,\n\t\t},\n\t}\n\n\tdata, err := c.Execute(ctx, req)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to fetch team states: %w\", err)\n\t}\n\n\tvar teamResp TeamResponse\n\tif err := json.Unmarshal(data, &teamResp); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse team states response: %w\", err)\n\t}\n\n\tif teamResp.Team.States == nil {\n\t\treturn nil, fmt.Errorf(\"no states found for team\")\n\t}\n\n\treturn teamResp.Team.States.Nodes, nil\n}\n\n// GetTeamLabels returns all issue labels defined for the team (paginated).\nfunc (c *Client) GetTeamLabels(ctx context.Context) ([]Label, error) {\n\tconst pageSize = 250\n\tquery := `","sourceCodeStart":627,"sourceCodeEnd":663,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/client.go#L627-L663","documentation":"GetTeamStates wraps any Execute failure with this message when fetching a team's workflow states. The wrapped cause is the underlying failure: GraphQL error (usually an unknown team ID), auth failure, rate limiting, or network error. Callers like BuildStateCache depend on this succeeding to map states.","triggerScenarios":"Calling GetTeamStates (directly or via BuildStateCache) when: the configured TeamID doesn't exist in the workspace (Linear returns 'Team not found' GraphQL error), the API token lacks access to that team, OAuth token refresh failed on 401, or Linear is rate-limiting/unreachable.","commonSituations":"Misconfigured LINEAR_TEAM_ID (typo or ID from another workspace); token created before the team existed or without team access; hitting rate limits right after a large sync; Linear outage.","solutions":["Check the wrapped cause — 'GraphQL errors: Team not found' almost always means TeamID is wrong","Verify the team ID by querying Linear for the workspace's teams with the same token","Regenerate/replace the API key if the wrapped error is 401/403","Wait for rate-limit reset if the cause is 'max retries' / 'rate limited'","Confirm the token's scopes include read access to workflow states"],"exampleFix":"// before\nstates, err := client.GetTeamStates(ctx)\n// after: distinguish bad team ID from transient failures\nif err != nil {\n    if strings.Contains(err.Error(), \"not found\") {\n        log.Fatalf(\"TeamID %q invalid — list teams with the same token\", client.TeamID)\n    }\n    return fmt.Errorf(\"transient, retry later: %w\", err)\n}","handlingStrategy":"validation","validationCode":"// Validate team access before building the state cache\nprobe := `query { viewer { id } }`\nif _, err := client.Execute(ctx, &linear.GraphQLRequest{Query: probe}); err != nil {\n    return fmt.Errorf(\"token or connectivity invalid before GetTeamStates: %w\", err)\n}\nif client.TeamID == \"\" {\n    return errors.New(\"linear: TeamID must be configured\")\n}","typeGuard":null,"tryCatchPattern":"states, err := client.GetTeamStates(ctx)\nif err != nil {\n    if strings.Contains(err.Error(), \"not found\") || strings.Contains(err.Error(), \"GraphQL errors\") {\n        return fmt.Errorf(\"configuration error (TeamID=%q): %w\", client.TeamID, err) // no retry\n    }\n    return retryWithBackoff(ctx, func() ([]linear.State, error) { return client.GetTeamStates(ctx) })\n}","preventionTips":["Confirm TeamID by listing teams with the same token during setup","Check token scopes include team/state read access","Throttle state-cache rebuilds to avoid rate limits","Handle the wrapped cause distinctly: config vs transient"],"tags":["linear","graphql","team-id","api-error"],"backgroundTag":"linear-team-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}