What causes "Failed to build dependency resolver: %v" in gastownhall/beads?

Inspect the wrapped error for the underlying storage failure and fix it (locks, connectivity to DB, disk).

Failed to build dependency resolver: %v

Error message

Failed to build dependency resolver: %v

What it means

While importing dependencies during pull, the engine could not construct the issue resolver used to translate external IDs to local issues (dependencyIssueResolver). All pending dependencies are then counted as failed and skipped. This is an upfront infrastructure failure, not a per-dependency problem.

Source

Thrown at internal/tracker/engine.go:1323

	if err := e.Store.RunInIssueLifecycleTransaction(ctx, fmt.Sprintf("bd: reimport update %s", c.IssueID), func(tx storage.IssueLifecycleTransaction) error {
		return applyPullIssueFields(ctx, tx, c.IssueID, updates, e.Actor)
	}); err != nil {
		e.warn("Failed to update %s during reimport: %v", c.IssueID, err)
	}
}

// createDependencies creates dependencies from the pending list, matching
// external IDs to local issue IDs. Returns the number of dependencies that
// failed to resolve or create.
func (e *Engine) createDependencies(ctx context.Context, deps []DependencyInfo) int {
	if len(deps) == 0 {
		return 0
	}

	resolveIssue, err := e.dependencyIssueResolver(ctx, nil)
	if err != nil {
		e.warn("Failed to build dependency resolver: %v", err)
		return len(deps)
	}

	errCount := 0
	for _, dep := range deps {
		fromIssue, err := resolveIssue(ctx, dep.FromExternalID)
		if err != nil {
			e.warn("Failed to resolve dependency source %s: %v", dep.FromExternalID, err)
			errCount++
			continue
		}
		toIssue, err := resolveIssue(ctx, dep.ToExternalID)
		if err != nil {
			e.warn("Failed to resolve dependency target %s: %v", dep.ToExternalID, err)
			errCount++
			continue
		}

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped error for the underlying storage failure and fix it (locks, connectivity to DB, disk).
Re-run `bd pull` — dependency creation is idempotent and will retry on the next pull.
Verify DB health (integrity check) if the resolver keeps failing.
Ensure the bd process has write access to the .beads storage.

Example fix

// before: another bd process holds the DB lock
bd sync --pull-only &
bd doctor
// after: stop competing processes, then pull
bd doctor
bd pull

Defensive patterns

Strategy: retry

Validate before calling

// verify storage is available before pulls that import dependencies
if err := store.Ping(ctx); err != nil {
    log.Fatalf("dependency import will fail: storage unavailable: %v", err)
}

Try / catch

// retry the pull — the resolver rebuild is cheap and edges are idempotent
for i := 0; i < 3; i++ {
    stats, err := engine.Sync(ctx, opts)
    if err == nil { break }
    if isStorageErr(err) { time.Sleep(backoff(i)); continue }
    break
}

Prevention

Run bd doctor before dependency-heavy pulls
No concurrent bd processes on the same database
Check .beads directory write permissions
Investigate repeated resolver-build failures as storage degradation

When it happens

Trigger: e.dependencyIssueResolver(ctx, nil) returns an error at the start of createDependencies — typically a failure to build the external-ref → local-issue lookup (storage query failure, DB lock, or store unavailable).

Common situations: Local database locked or unavailable during pull; storage driver error while prefetching the ref-to-issue index; large-scale DB degradation after a crash.

Related errors

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