gastownhall/beads · error

failed to parse create response: %w

Error message

failed to parse create response: %w

What it means

After the issueCreate mutation succeeds at the transport level, the response is unmarshalled into IssueCreateResponse. This error wraps JSON decoding failures, meaning the HTTP call returned but the body is not the expected `{ issueCreate: { success, issue } }` shape.

Source

Thrown at internal/linear/client.go:855

	}
	return input
}

// CreateIssue creates a new issue in Linear.
func (c *Client) CreateIssue(ctx context.Context, title, description string, priority int, stateID string, labelIDs []string) (*Issue, error) {
	req := &GraphQLRequest{
		Query:     issueCreateMutation,
		Variables: map[string]interface{}{"input": c.buildIssueCreateInput(title, description, priority, stateID, labelIDs)},
	}

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

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

	if !createResp.IssueCreate.Success {
		return nil, fmt.Errorf("issue creation reported as unsuccessful")
	}

	return &createResp.IssueCreate.Issue, nil
}

// createIssueSingleAttempt executes the issueCreate mutation exactly once,
// without the retry loop used by Execute. This is intentional: retrying a
// mutation that may have already reached Linear risks creating a duplicate.
// The caller (CreateIssueIdempotent) handles retry safety by re-searching for
// the idempotency marker after any failure.
func (c *Client) createIssueSingleAttempt(ctx context.Context, title, description string, priority int, stateID string, labelIDs []string) (*Issue, error) {
	req := &GraphQLRequest{
		Query:     issueCreateMutation,
		Variables: map[string]interface{}{"input": c.buildIssueCreateInput(title, description, priority, stateID, labelIDs)},

View on GitHub (pinned to 71377f2769)

Solutions

1. Dump the raw `data` bytes when this error occurs to see the actual body shape.
2. Confirm c.Endpoint points to https://api.linear.app/graphql.
3. Surface any GraphQL `errors` array from the response before unmarshalling into IssueCreateResponse.
4. Update IssueCreateResponse if the Linear issueCreate payload schema changed.

Example fix

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

// ensure we are talking to the GraphQL endpoint
if !strings.HasSuffix(client.Endpoint, "/graphql") {
    return errors.New("issueCreate requires the Linear GraphQL endpoint")
}

func isSuccessResponse(data []byte) bool {
    var probe struct {
        IssueCreate *struct {
            Success *bool `json:"success"`
        } `json:"issueCreate"`
    }
    return json.Unmarshal(data, &probe) == nil && probe.IssueCreate != nil && probe.IssueCreate.Success != nil
}

issue, err := client.CreateIssue(ctx, title, desc, pri, stateID, labels)
if err != nil {
    var typeErr *json.UnmarshalTypeError
    if errors.As(err, &typeErr) {
        log.Printf("issueCreate response shape changed: %s", typeErr.Field)
        return errUnexpectedPayload
    }
    return err
}

When it happens

Trigger: Response body deviates from IssueCreateResponse — GraphQL error partial payloads (success field absent → unmarshal type mismatch), proxy HTML bodies with 200 status, endpoint misconfiguration, Linear schema changes to the issueCreate payload.

Common situations: Hitting the wrong URL (REST endpoint), intermediary proxies or captive portals, truncated responses, Linear API payload changes.

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 team labels response: %w
• failed to parse description search response: %w
• failed to parse update project response: %w
• existing milestone metadata is not a JSON object: %w
• marshaling Linear milestone metadata: %w

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