gastownhall/beads · error

failed to parse description search response

Error message

failed to parse description search response: %w

What it means

Once the description-search query succeeds, the response bytes are unmarshalled into IssuesResponse. This error wraps a JSON unmarshal failure, meaning the HTTP call worked but the body does not match the expected `{ issues: { nodes: [...] } }` shape.

Solutions

1. Log the raw response body alongside the unmarshal error to see the actual payload.
2. Confirm the endpoint URL is https://api.linear.app/graphql.
3. Check for and surface any GraphQL `errors` array in the response before/instead of unmarshalling.
4. Update IssuesResponse struct fields if the Linear schema changed.

Example fix

// before
if err := json.Unmarshal(data, &issuesResp); err != nil {
    return nil, fmt.Errorf("failed to parse description search response: %w", err)
}
// after
if err := json.Unmarshal(data, &issuesResp); err != nil {
    return nil, fmt.Errorf("failed to parse description search response: %w (body: %.200s)", err, data)
}

// verify endpoint before search
if client.Endpoint != "https://api.linear.app/graphql" {
    return errors.New("unexpected Linear endpoint")
}

func validIssuesPayload(data []byte) bool {
    var probe struct {
        Issues *struct {
            Nodes []json.RawMessage `json:"nodes"`
        } `json:"issues"`
    }
    return json.Unmarshal(data, &probe) == nil && probe.Issues != nil
}

issue, err := client.FindIssueByDescriptionContains(ctx, desc)
if err != nil {
    var typeErr *json.UnmarshalTypeError
    if errors.As(err, &typeErr) {
        log.Printf("unexpected search response shape at %s; skipping dedupe", typeErr.Field)
        return nil // proceed without dedupe or use cache
    }
    return err
}

When it happens

Trigger: Linear returns 200 with a body that doesn't fit IssuesResponse — GraphQL error partial payloads, schema changes to the issues connection, proxy/HTML error bodies with a 200 status, or truncated responses.

Common situations: Hitting the wrong endpoint (REST instead of /graphql), corporate proxies returning HTML interstitials, Linear schema updates renaming `issues` or `nodes`, mid-request connection drops producing truncated JSON.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

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

Related errors

• failed to parse create response
• failed to parse team labels response
• failed to parse update project response
• existing milestone metadata is not a JSON object
• failed to marshal request

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

Appendix: source

Thrown at internal/linear/client.go:786

			"contains": text,
		},
	}

	req := &GraphQLRequest{
		Query: query,
		Variables: map[string]interface{}{
			"filter": filter,
		},
	}

	data, err := c.Execute(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("failed to search issues by description: %w", err)
	}

	var issuesResp IssuesResponse
	if err := json.Unmarshal(data, &issuesResp); err != nil {
		return nil, fmt.Errorf("failed to parse description search response: %w", err)
	}

	if len(issuesResp.Issues.Nodes) > 0 {
		return &issuesResp.Issues.Nodes[0], nil
	}
	return nil, nil
}

// issueCreateMutation is the GraphQL mutation for creating a Linear issue.
const issueCreateMutation = `
	mutation CreateIssue($input: IssueCreateInput!) {
		issueCreate(input: $input) {
			success
			issue {
				id
				identifier
				title
				description

View on GitHub (pinned to 71377f2769)