gastownhall/beads · error

failed to parse work item types value: %w

Error message

failed to parse work item types value: %w

What it means

This error means the work-item-types envelope decoded but the nested 'value' array could not be unmarshalled into []WorkItemType — the items' field types differ from the struct (schema drift or fixture mismatch).

Source

Thrown at internal/ado/client.go:602

	return projects, nil
}

// GetWorkItemTypes returns the work item types available in the project.
func (c *Client) GetWorkItemTypes(ctx context.Context) ([]WorkItemType, error) {
	urlStr := addAPIVersion(c.apiBase() + "/wit/workitemtypes")
	respBody, err := c.doRequest(ctx, http.MethodGet, urlStr, "", nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get work item types: %w", err)
	}

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

	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

View on GitHub (pinned to 71377f2769)

Solutions

1. Dump envelope.Value raw JSON and compare item field types with the WorkItemType struct
2. Check whether ADO changed the workitemtypes schema for the api-version in use; pin or update the version
3. Upgrade the ado package to match current ADO schema
4. Fix test fixtures so 'value' items match WorkItemType field types

Example fix

// before (fixture)
{"value": [{"name": "Bug", "color": 0}]}
// after
{"count": 1, "value": [{"name": "Bug", "referenceName": "Microsoft.VSTS.WorkItemTypes.Bug", "color": "cc2936"}]}

func workItemTypeArrayOK(raw json.RawMessage) bool {
  var arr []map[string]any
  if json.Unmarshal(raw, &arr) != nil {
    return false
  }
  for _, it := range arr {
    if _, ok := it["name"].(string); !ok {
      return false
    }
  }
  return true
}

types, err := client.GetWorkItemTypes(ctx)
if err != nil {
  if strings.Contains(err.Error(), "failed to parse work item types value") {
    return nil, fmt.Errorf("workitemtypes schema drift — pin api-version or upgrade library: %w", err)
  }
  return nil, err
}

When it happens

Trigger: Calling GetWorkItemTypes when ADO's workitemtypes payload items don't match the WorkItemType struct's expected field types (e.g. color/referenceName type changes), or 'value' is not an array.

Common situations: ADO API schema changes between api-versions; custom process templates returning extra/mis-typed fields; stale test fixtures from a mock server.

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

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