What causes "unable to find orphaned issues: %w" in gastownhall/beads?

Fix the wrapped cause (typically 'no database available'): run in a repo with an initialized beads DB or pass --db.

unable to find orphaned issues: %w

Error message

unable to find orphaned issues: %w

What it means

findOrphanedIssues first obtains an IssueProvider via getIssueProvider; any failure there is wrapped as 'unable to find orphaned issues: %w'. Most commonly the wrapped cause is 'no database available', but any provider-construction failure surfaces under this message.

Source

Thrown at cmd/bd/orphans.go:196

	if store != nil {
		return &doltStoreProvider{labels: labels, labelsAny: labelsAny}, func() {}, nil
	}
	return nil, nil, fmt.Errorf("no database available")
}

// getIssueProvider returns an IssueProvider backed by the global Dolt store.
// labels and labelsAny are passed through to SearchIssues for label filtering.
func getIssueProvider(labels, labelsAny []string) (types.IssueProvider, func(), error) {
	return getIssueProviderFn(labels, labelsAny)
}

// findOrphanedIssues wraps the shared doctor package function and converts to output format.
// It respects the --db flag for cross-repo orphan detection.
// labels and labelsAny are passed to the issue provider to restrict which issues are considered.
func findOrphanedIssues(path string, labels, labelsAny []string) ([]orphanIssueOutput, error) {
	provider, cleanup, err := getIssueProvider(labels, labelsAny)
	if err != nil {
		return nil, fmt.Errorf("unable to find orphaned issues: %w", err)
	}
	defer cleanup()

	return findOrphanedIssuesWithProvider(path, provider)
}

func findOrphanedIssuesWithProvider(path string, provider types.IssueProvider) ([]orphanIssueOutput, error) {
	orphans, err := doctorFindOrphanedIssues(path, provider)
	if err != nil {
		return nil, fmt.Errorf("unable to find orphaned issues: %w", err)
	}

	var output []orphanIssueOutput
	for _, orphan := range orphans {
		output = append(output, orphanIssueOutput{
			IssueID:             orphan.IssueID,
			Title:               orphan.Title,
			Status:              orphan.Status,

View on GitHub (pinned to 71377f2769)

Solutions

Fix the wrapped cause (typically 'no database available'): run in a repo with an initialized beads DB or pass --db.
Run 'bd init' to create a database if missing.
Verify Dolt/driver health with 'bd doctor'.
For proxied mode, confirm the server opened its store before proxying the orphans call.

Example fix

// before
bd doctor conventions orphans   # no DB open -> unable to find orphaned issues: no database available
// after
bd init && bd doctor conventions orphans

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(filepath.Join(path, ".beads")); err != nil {
    return fmt.Errorf("no beads database at %s: %w", path, err)
}
// then call findOrphanedIssues

Try / catch

orphans, err := findOrphanedIssues(path, labels, labelsAny)
if err != nil {
    var inner error
    if errors.As(err, &inner) && strings.Contains(inner.Error(), "no database available") {
        // initialize/open the DB, then retry
    }
    return err
}

Prevention

Verify the beads DB exists at the target path before scanning
Run bd init for fresh repos
Check Dolt health via bd doctor
Handle the wrapped cause, not just the wrapper message

When it happens

Trigger: getIssueProvider returns an error inside findOrphanedIssues — i.e. the global store is nil or the provider factory fails — when called from runConventionsOrphans, tests, or anonymous callers of 'bd orphans'/'bd doctor'.

Common situations: 'bd orphans' or 'bd doctor conventions orphans' executed without an open database, with a bad --db path, or in an environment where the Dolt store couldn't start.

Related errors

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