What causes "failed to fetch issues: %w" in gastownhall/beads?

Unwrap the %w cause — the inner message says exactly which failure occurred

failed to fetch issues: %w

Error message

failed to fetch issues: %w

What it means

FetchIssues wraps any error from Client.Execute with this message while fetching a page of issues. The wrapped cause is the real failure: GraphQL errors, rate limiting, retries exhausted, HTTP API errors, or context cancellation.

Source

Thrown at internal/linear/client.go:506

			return nil, fmt.Errorf("pagination limit exceeded: stopped after %d pages", MaxPages)
		}

		variables := map[string]interface{}{
			"filter": filter,
			"first":  MaxPageSize,
		}
		if cursor != "" {
			variables["after"] = cursor
		}

		req := &GraphQLRequest{
			Query:     issuesQuery,
			Variables: variables,
		}

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

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

		allIssues = append(allIssues, issuesResp.Issues.Nodes...)

		if !issuesResp.Issues.PageInfo.HasNextPage {
			break
		}
		cursor = issuesResp.Issues.PageInfo.EndCursor
	}

	return allIssues, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

Unwrap the %w cause — the inner message says exactly which failure occurred
If it's auth-related, regenerate the Linear API key and update configuration
If it's a GraphQL error, check TeamID/ProjectID against the actual workspace
If rate-limited, back off and retry later or reduce sync frequency
Check Linear's status page for outages

Example fix

// before
issues, err := client.FetchIssues(ctx, "open")
// after: inspect the wrapped cause
if err != nil {
    log.Printf("FetchIssues failed: %v", errors.Unwrap(err))
    return fmt.Errorf("sync aborted: %w", err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

if client.TeamID == "" || token == "" {
    return errors.New("linear: missing TEAM_ID or API token")
}

Try / catch

issues, err := client.FetchIssues(ctx, "open")
if err != nil {
    var root = errors.Unwrap(err)
    switch {
    case strings.Contains(err.Error(), "GraphQL errors:"):
        return fmt.Errorf("bad filter/config: %w", err) // do not retry
    case strings.Contains(err.Error(), "max retries"):
        return retryLater(err) // transient
    default:
        return err
    }
}

Prevention

Validate TeamID/token at client construction with a cheap query
Unwrap errors to branch on the real cause before deciding to retry
Persist sync state so a failed page fetch can resume, not restart
Watch rate-limit headers during bulk operations

When it happens

Trigger: Any Execute failure inside the FetchIssues pagination loop: invalid team ID filter (GraphQL errors), 429 rate-limit storm leading to 'max retries exceeded', network failure, 401/403 auth failures (non-OAuth clients don't retry 401), or HTTP 5xx from Linear.

Common situations: Expired or revoked LINEAR_API_KEY; wrong LINEAR_TEAM_ID causing a GraphQL rejection; hitting Linear rate limits during a large sync; transient outage mid-pagination.

Related errors

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