What causes "failed to check destination repository: %w" in gastownhall/beads?

Inspect the wrapped inner error for the storage-level cause

failed to check destination repository: %w

Error message

failed to check destination repository: %w

What it means

This error wraps failures from the destination-repository preflight check in validateRepos, which probes the --to repo for existing issues. It means the validation query errored — note that an empty destination is NOT an error; it only prints an informational message that the repo will be created. The wrapped error holds the real cause.

Source

Thrown at cmd/bd/migrate_issues.go:237

	if len(fromIssues) == 0 {
		msg := fmt.Sprintf("source repository '%s' has no issues", from)
		if strict {
			return fmt.Errorf("%s", msg)
		}
		if !jsonOutput {
			fmt.Fprintf(os.Stderr, "Warning: %s\n", msg)
		}
	}

	// Check if destination repo exists (just a warning)
	toIssues, err := s.SearchIssues(ctx, "", types.IssueFilter{
		SourceRepo:    &to,
		Limit:         1,
		MaxRows:       0,
		MaxRowsSource: "",
	})
	if err != nil {
		return fmt.Errorf("failed to check destination repository: %w", err)
	}

	if len(toIssues) == 0 && !jsonOutput {
		fmt.Fprintf(os.Stderr, "Info: destination repository '%s' will be created\n", to)
	}

	return nil
}

func findCandidateIssues(ctx context.Context, s storage.DoltStorage, p migrateIssuesParams) ([]string, error) {
	// Build filter from params. Opt out of BEADS_MAX_ROWS (designer §4.1) —
	// migrate-issues is round-trip and must enumerate every candidate.
	filter := types.IssueFilter{
		SourceRepo:    &p.from,
		MaxRows:       0,
		MaxRowsSource: "",
	}

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped inner error for the storage-level cause
Validate the --to repo name contains only legal characters
Run `bd doctor` to rule out local database problems
Retry if the failure was a transient lock

Defensive patterns

Strategy: try-catch

Validate before calling

# rule out local storage problems before migrating
bd doctor
# validate the destination name characters
[[ "$to" =~ ^[A-Za-z0-9._-]+$ ]] || echo "invalid repo name"

Try / catch

if err := runMigrate(); err != nil {
    if strings.Contains(err.Error(), "failed to check destination repository") {
        log.Printf("destination probe failed: %v", errors.Unwrap(err))
    }
    return err
}

Prevention

Use simple, legal repo names for --to
Run bd doctor if preflight checks keep failing
Avoid concurrent bd processes during migration

When it happens

Trigger: validateRepos' destination query (SourceRepo=&to, Limit=1) returns a non-nil error during executeMigrateIssues preflight.

Common situations: Storage error probing a not-yet-created destination repo path; database lock from a concurrent bd process; invalid characters in the --to repo name rejected by the store layer.

Related errors

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