gastownhall/beads · error

failed to parse team states response: %w

Error message

failed to parse team states response: %w

What it means

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.

Source

Thrown at internal/linear/client.go:650

			}
		}
	`

	req := &GraphQLRequest{
		Query: query,
		Variables: map[string]interface{}{
			"teamId": c.TeamID,
		},
	}

	data, err := c.Execute(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("failed to fetch team states: %w", err)
	}

	var teamResp TeamResponse
	if err := json.Unmarshal(data, &teamResp); err != nil {
		return nil, fmt.Errorf("failed to parse team states response: %w", err)
	}

	if teamResp.Team.States == nil {
		return nil, fmt.Errorf("no states found for team")
	}

	return teamResp.Team.States.Nodes, nil
}

// GetTeamLabels returns all issue labels defined for the team (paginated).
func (c *Client) GetTeamLabels(ctx context.Context) ([]Label, error) {
	const pageSize = 250
	query := `
		query TeamLabels($teamId: String!, $first: Int!, $after: String) {
			team(id: $teamId) {
				labels(first: $first, after: $after) {
					nodes {
						id

View on GitHub (pinned to 71377f2769)

Solutions

1. Log the raw data payload to inspect the actual response shape
2. Check Linear's changelog for changes to the team/states query
3. Update the TeamStates query and TeamResponse/State structs to match the current schema
4. Upgrade beads to a version compatible with Linear's current API

Example fix

// after: surface the raw payload when decode fails
var teamResp TeamResponse
if err := json.Unmarshal(data, &teamResp); err != nil {
    log.Printf("linear team payload: %s", string(data))
    return nil, fmt.Errorf("failed to parse team states response: %w", err)
}

if _, err := client.GetTeamStates(ctx); err != nil &&
    strings.Contains(err.Error(), "failed to parse team states response") {
    // don't retry — schema drift; alert and upgrade client
    return fmt.Errorf("linear schema mismatch, upgrade client: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse issues response: %w
• failed to parse issue from JSONL: %w
• failed to parse update project response: %w
• unable to parse plugin file v2: %w
• parsing JSON: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/eaa982a26f4dc034. Report an issue: GitHub.