gastownhall/beads · error

failed to fetch issue by identifier: %w

Error message

failed to fetch issue by identifier: %w

What it means

FetchIssueByIdentifier runs an issues(filter:...) GraphQL query to resolve an identifier like TEAM-123. This error wraps any failure from the underlying Execute call: network errors, HTTP errors, GraphQL errors (invalid filter, bad auth), or context cancellation. It does not mean the issue was absent — not-found returns (nil, nil).

Source

Thrown at internal/linear/client.go:1308

	// Extract the issue number from identifier (e.g., "123" from "TEAM-123")
	parts := strings.Split(identifier, "-")
	if len(parts) >= 2 {
		if number, err := strconv.Atoi(parts[len(parts)-1]); err == nil {
			// Add number filter for more precise matching
			variables["filter"].(map[string]interface{})["number"] = map[string]interface{}{
				"eq": number,
			}
		}
	}

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

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

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

	// Find the exact match by identifier (in case of partial matches)
	for _, issue := range issuesResp.Issues.Nodes {
		if issue.Identifier == identifier {
			return &issue, nil
		}
	}

	return nil, nil // Issue not found
}

// BuildStateCache fetches and caches team states.

View on GitHub (pinned to 71377f2769)

Solutions

1. Unwrap the error (errors.Unwrap / errors.Is) to see the underlying transport or GraphQL failure.
2. Verify the Linear API key is valid: run a trivial query like FetchTeams with the same client.
3. Check rate limits — Linear returns 429 under bulk fetching; back off and retry with jitter.
4. Confirm network/proxy access to the Linear GraphQL endpoint and retry; the call is idempotent (read-only).
5. If the wrapped error mentions authentication, regenerate the API key in Linear settings.

Example fix

// before
issue, err := client.FetchIssueByIdentifier(ctx, "ENG-123")
if err != nil { return err }
// after
issue, err := client.FetchIssueByIdentifier(ctx, "ENG-123")
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) { return retryWithBackoff(...) }
    return fmt.Errorf("lookup ENG-123: %w", err)
}

// validate identifier shape before calling
var identRe = regexp.MustCompile(`^[A-Za-z0-9]+-\d+$`)
if !identRe.MatchString(identifier) {
    return fmt.Errorf("malformed identifier %q; expected TEAM-123", identifier)
}

issue, err := client.FetchIssueByIdentifier(ctx, ident)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) || isNetworkErr(err) {
        return retryWithBackoff(3, time.Second, func() (*Issue, error) {
            return client.FetchIssueByIdentifier(ctx, ident)
        })
    }
    return nil, fmt.Errorf("lookup %s: %w", ident, err)
}
// note: err == nil && issue == nil means not found

When it happens

Trigger: c.Execute(ctx, req) returns an error when querying issues with a team/number filter: expired or invalid API key, network failure, rate limiting (429), GraphQL validation error on the IssueFilter, or ctx cancelled/deadline exceeded.

Common situations: LINEAR_API_KEY revoked or rotated; expired auth token after long-running sync; rate limit hit during bulk lookups; corporate proxy/DNS blocking linear.app; malformed identifier causing an invalid number filter is NOT this error (it silently skips the filter).

Related errors

• failed to fetch teams: %w
• failed to fetch projects: %w
• failed to parse update response: %w
• batch create failed and recovery search also failed: %w (bat
• batch create failed; %d of %d issues unconfirmed (batch erro

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