gastownhall/beads · error

failed to parse update project response: %w

Error message

failed to parse update project response: %w

What it means

UpdateProject fails with this when the raw JSON returned by Linear cannot be unmarshaled into ProjectUpdateResponse. This indicates the HTTP call succeeded but the payload shape is not what this client expects — an API contract change or a non-JSON response (proxy error page, HTML error, truncated body).

Source

Thrown at internal/linear/client.go:1584

		}
	`

	req := &GraphQLRequest{
		Query: query,
		Variables: map[string]interface{}{
			"id":    projectID,
			"input": updates,
		},
	}

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

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

	if !updateResp.ProjectUpdate.Success {
		return nil, fmt.Errorf("project update reported as unsuccessful")
	}

	return &updateResp.ProjectUpdate.Project, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Log the raw response body (data) at failure time to see what was actually returned.
2. Verify the client's base URL points to the official Linear GraphQL endpoint.
3. Check for proxy/gateway interference (HTML instead of JSON) in the response body.
4. Update the client library if Linear changed the ProjectUpdate payload shape.
5. Confirm Content-Type of the response is application/json.

Example fix

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

if len(data) == 0 {
	return fmt.Errorf("empty response body from Linear")
}
if !json.Valid(data) {
	return fmt.Errorf("non-JSON response from Linear: %.100s", data)
}

var updateResp ProjectUpdateResponse
if err := json.Unmarshal(data, &updateResp); err != nil {
	log.Printf("linear raw response: %s", data)
	return nil, fmt.Errorf("failed to parse update project response: %w", err)
}

When it happens

Trigger: Client.UpdateProject receives data whose JSON structure does not match ProjectUpdateResponse (missing/renamed fields, wrong content type, HTML error page from a proxy, truncated response).

Common situations: Corporate proxy or auth gateway returning an HTML login page, Linear API schema changes after an update, misconfigured base URL pointing at a non-Linear endpoint, response truncation on very large payloads.

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 issues response: %w
• failed to parse team states response: %w
• failed to parse team labels response: %w
• failed to parse description search response: %w
• failed to parse create response: %w

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