{"record":{"id":"eaa982a26f4dc034","repo":"gastownhall/beads","slug":"failed-to-parse-team-states-response-w","errorCode":null,"errorMessage":"failed to parse team states response: %w","messagePattern":"failed to parse team states response: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/client.go","lineNumber":650,"sourceCode":"\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 := `\n\t\tquery TeamLabels($teamId: String!, $first: Int!, $after: String) {\n\t\t\tteam(id: $teamId) {\n\t\t\t\tlabels(first: $first, after: $after) {\n\t\t\t\t\tnodes {\n\t\t\t\t\t\tid","sourceCodeStart":632,"sourceCodeEnd":668,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/client.go#L632-L668","documentation":"GetTeamStates fetched successfully but the JSON 'data' payload could not be decoded into TeamResponse. This means the response's team.states shape no longer matches the client's expected `team.states.nodes{id,name,type}` structure.","triggerScenarios":"Execute succeeded but unmarshaling failed: Linear changed the TeamStates schema (e.g. states moved off the team object to a workflowStates query), fields renamed, or types changed so the strict decode fails.","commonSituations":"Linear API deprecating `team.states` in favor of `workflowStates` while the client still queries the old shape; running an old beads binary against the current Linear API; a proxy returning altered JSON.","solutions":["Log the raw data payload to inspect the actual response shape","Check Linear's changelog for changes to the team/states query","Update the TeamStates query and TeamResponse/State structs to match the current schema","Upgrade beads to a version compatible with Linear's current API"],"exampleFix":"// after: surface the raw payload when decode fails\nvar teamResp TeamResponse\nif err := json.Unmarshal(data, &teamResp); err != nil {\n    log.Printf(\"linear team payload: %s\", string(data))\n    return nil, fmt.Errorf(\"failed to parse team states response: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if _, err := client.GetTeamStates(ctx); err != nil &&\n    strings.Contains(err.Error(), \"failed to parse team states response\") {\n    // don't retry — schema drift; alert and upgrade client\n    return fmt.Errorf(\"linear schema mismatch, upgrade client: %w\", err)\n}","preventionTips":["Keep the client updated against Linear's current GraphQL schema","Log the raw payload on unmarshal failure to speed diagnosis","Avoid intermediate proxies that rewrite API JSON","Add regression tests decoding recorded Linear responses"],"tags":["json","parsing","linear","schema"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}