{"record":{"id":"8de8428d0bf7eda4","repo":"gastownhall/beads","slug":"failed-to-parse-work-item-types-value-w","errorCode":null,"errorMessage":"failed to parse work item types value: %w","messagePattern":"failed to parse work item types value: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/ado/client.go","lineNumber":602,"sourceCode":"\treturn projects, nil\n}\n\n// GetWorkItemTypes returns the work item types available in the project.\nfunc (c *Client) GetWorkItemTypes(ctx context.Context) ([]WorkItemType, error) {\n\turlStr := addAPIVersion(c.apiBase() + \"/wit/workitemtypes\")\n\trespBody, err := c.doRequest(ctx, http.MethodGet, urlStr, \"\", nil)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get work item types: %w\", err)\n\t}\n\n\tvar envelope listResponse\n\tif err := json.Unmarshal(respBody, &envelope); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse work item types response: %w\", err)\n\t}\n\n\tvar types []WorkItemType\n\tif err := json.Unmarshal(envelope.Value, &types); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse work item types value: %w\", err)\n\t}\n\treturn types, nil\n}\n\n// GetWorkItemStates returns the states for a given work item type.\nfunc (c *Client) GetWorkItemStates(ctx context.Context, typeName string) ([]WorkItemState, error) {\n\turlStr := addAPIVersion(c.apiBase() + \"/wit/workitemtypes/\" + url.PathEscape(typeName) + \"/states\")\n\trespBody, err := c.doRequest(ctx, http.MethodGet, urlStr, \"\", nil)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get work item states: %w\", err)\n\t}\n\n\tvar envelope listResponse\n\tif err := json.Unmarshal(respBody, &envelope); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to parse work item states response: %w\", err)\n\t}\n\n\tvar states []WorkItemState","sourceCodeStart":584,"sourceCodeEnd":620,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/ado/client.go#L584-L620","documentation":"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).","triggerScenarios":"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.","commonSituations":"ADO API schema changes between api-versions; custom process templates returning extra/mis-typed fields; stale test fixtures from a mock server.","solutions":["Dump envelope.Value raw JSON and compare item field types with the WorkItemType struct","Check whether ADO changed the workitemtypes schema for the api-version in use; pin or update the version","Upgrade the ado package to match current ADO schema","Fix test fixtures so 'value' items match WorkItemType field types"],"exampleFix":"// before (fixture)\n{\"value\": [{\"name\": \"Bug\", \"color\": 0}]}\n// after\n{\"count\": 1, \"value\": [{\"name\": \"Bug\", \"referenceName\": \"Microsoft.VSTS.WorkItemTypes.Bug\", \"color\": \"cc2936\"}]}","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"func workItemTypeArrayOK(raw json.RawMessage) bool {\n  var arr []map[string]any\n  if json.Unmarshal(raw, &arr) != nil {\n    return false\n  }\n  for _, it := range arr {\n    if _, ok := it[\"name\"].(string); !ok {\n      return false\n    }\n  }\n  return true\n}","tryCatchPattern":"types, err := client.GetWorkItemTypes(ctx)\nif err != nil {\n  if strings.Contains(err.Error(), \"failed to parse work item types value\") {\n    return nil, fmt.Errorf(\"workitemtypes schema drift — pin api-version or upgrade library: %w\", err)\n  }\n  return nil, err\n}","preventionTips":["Pin the api-version matched to your library version","Regenerate fixtures from live ADO responses after process-template changes","Upgrade the library when ADO ships schema changes","Validate fixture 'value' items against WorkItemType field types"],"tags":["json","parsing","azure-devops","schema-mismatch"],"backgroundTag":"json-decode-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}