gastownhall/beads · error

failed to parse work item states response: %w

Error message

failed to parse work item states response: %w

What it means

This error means GetWorkItemStates got a response whose body could not be decoded into the listResponse envelope — json.Unmarshal of the raw body failed. The response was not the expected {"value": [...]} JSON (HTML page, empty body, or malformed JSON).

Source

Thrown at internal/ado/client.go:617

	var types []WorkItemType
	if err := json.Unmarshal(envelope.Value, &types); err != nil {
		return nil, fmt.Errorf("failed to parse work item types value: %w", err)
	}
	return types, nil
}

// GetWorkItemStates returns the states for a given work item type.
func (c *Client) GetWorkItemStates(ctx context.Context, typeName string) ([]WorkItemState, error) {
	urlStr := addAPIVersion(c.apiBase() + "/wit/workitemtypes/" + url.PathEscape(typeName) + "/states")
	respBody, err := c.doRequest(ctx, http.MethodGet, urlStr, "", nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get work item states: %w", err)
	}

	var envelope listResponse
	if err := json.Unmarshal(respBody, &envelope); err != nil {
		return nil, fmt.Errorf("failed to parse work item states response: %w", err)
	}

	var states []WorkItemState
	if err := json.Unmarshal(envelope.Value, &states); err != nil {
		return nil, fmt.Errorf("failed to parse work item states value: %w", err)
	}
	return states, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Log the raw response body to see what came back instead of JSON
2. Ensure requests reach the API host, not an auth proxy or the web UI
3. Retry transient truncations
4. Verify project/org URL configuration points at the ADO REST API

states, err := client.GetWorkItemStates(ctx, typeName)
if err != nil {
  if strings.Contains(err.Error(), "failed to parse work item states response") {
    return nil, fmt.Errorf("non-JSON response for states of %q (proxy/HTML page?): %w", typeName, err)
  }
  return nil, err
}

When it happens

Trigger: Calling GetWorkItemStates when the states endpoint returns non-JSON: HTML auth/proxy page with 200, empty body from a misrouted URL, truncated response, or ADO error page.

Common situations: Corporate proxy injecting HTML; incorrect apiBase serving the web UI; network truncation on large responses; ADO degradation.

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 projects response: %w
• failed to parse work item types response: %w
• failed to parse projects value: %w
• failed to parse work item types value: %w
• parsing JSON: %w

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