gastownhall/beads · error

failed to find candidate issues: %w

Error message

failed to find candidate issues: %w

What it means

This error wraps any failure from findCandidateIssues during step 2 of `bd migrate-issues`, which builds the initial candidate set C of issues matching the user's filters. It indicates the store query for issues matching the --from-repo/filter parameters failed before migration planning could proceed. The wrapped inner error carries the actual cause (storage, query, or context failure).

Source

Thrown at cmd/bd/migrate_issues.go:142

	Orphans           int      `json:"orphans"`
	OrphanSamples     []string `json:"orphan_samples,omitempty"`
	IssueIDs          []string `json:"issue_ids"`
	From              string   `json:"from"`
	To                string   `json:"to"`
}

func executeMigrateIssues(ctx context.Context, p migrateIssuesParams) error {
	s := store // use global Storage interface

	// Step 1: Validate repositories exist
	if err := validateRepos(ctx, s, p.from, p.to, p.strict); err != nil {
		return err
	}

	// Step 2: Build initial candidate set C using filters
	candidates, err := findCandidateIssues(ctx, s, p)
	if err != nil {
		return fmt.Errorf("failed to find candidate issues: %w", err)
	}

	if len(candidates) == 0 {
		if jsonOutput {
			return outputJSON(map[string]interface{}{
				"message": "No issues match the specified filters",
			})
		}
		fmt.Println("Nothing to do: no issues match the specified filters")
		return nil
	}

	// Step 3: Expand set to M (migration set) based on --include
	migrationSet, dependencyStats, err := expandMigrationSet(ctx, s, candidates, p)
	if err != nil {
		return fmt.Errorf("failed to compute migration set: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped inner error (%w) to identify the actual store failure
2. Verify the database is healthy with `bd doctor` and that no other bd process holds a lock
3. Re-run with simpler filters to isolate which filter causes the query to fail
4. Check that the beads version matches the database schema (run any pending migrations)

Example fix

// before: bare call hides which filter failed
candidates, err := findCandidateIssues(ctx, s, p)
// after: log filters with the error for diagnosis
if err != nil {
    return fmt.Errorf("failed to find candidate issues (repo=%q filters=%v): %w", p.from, p.filters, err)
}

// before running migrate, confirm the source has matching issues
bd list --repo old-repo --limit 1
bd doctor

if err := runMigrate(); err != nil {
    var inner error
    if errors.As(err, &inner) || errors.Unwrap(err) != nil {
        log.Printf("candidate lookup failed: %v", errors.Unwrap(err))
    }
    return err
}

When it happens

Trigger: findCandidateIssues(ctx, s, p) returns a non-nil error while building the candidate set from the applied filters (repo, label, status, priority filters in the migrate params).

Common situations: Corrupt or locked Dolt database during migration; invalid filter combinations that the store query rejects; context cancellation because the user Ctrl-C'd a long-running migration; schema mismatch after a beads version upgrade.

Related errors

• resolving ID %s: %w
• failed to check parent issue: %w
• canonical issue not found: %s
• failed to add supersede link: %w
• batch create: %w

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