gastownhall/beads · warning

Failed to resolve dependency source

Error message

Failed to resolve dependency source %s: %v

What it means

During dependency import, the resolver failed (errored, not merely 'not found') while looking up the source issue of a dependency by its external ID. The dependency is skipped and counted as failed; other dependencies continue. A nil result with no error is treated as expected (issue never imported) and does not warn.

Solutions

1. Read the wrapped error to distinguish storage failure from data problems.
2. Re-run `bd pull` after fixing storage issues; unresolved dependencies are retried.
3. Check that the referenced external IDs in the tracker are well-formed.
4. Verify the dependency-owning issues were themselves imported (both endpoints must exist locally).
5. Use `bd doctor` or storage checks if lookup errors persist across runs.

Example fix

// before: dependency references an issue that was filtered out of the pull
bd pull --type=bug
// after: pull all types so dependency endpoints exist
bd pull

// validate dependency external IDs before pulling
for _, dep := range deps {
    if dep.FromExternalID == "" || dep.ToExternalID == "" {
        log.Printf("dependency with empty endpoint: %+v", dep)
    }
    if !tracker.IsExternalRef(dep.FromExternalID) || !tracker.IsExternalRef(dep.ToExternalID) {
        log.Printf("malformed dependency endpoint: %+v", dep)
    }
}

// re-run pull to retry failed edge resolutions
stats, err := engine.Sync(ctx, opts)
if stats != nil && stats.FailedDeps > 0 {
    time.Sleep(time.Second)
    engine.Sync(ctx, opts)
}

When it happens

Trigger: resolveIssue(ctx, dep.FromExternalID) returns a non-nil error — storage query failure while scanning external_ref index, DB lock, or malformed lookup — for the dependency's From side.

Common situations: DB contention during a large pull; corrupted external_ref values causing lookup errors; storage driver transient failure mid-import.

Related errors

• Failed to resolve dependency target
• Failed to build dependency resolver
• Failed to create dependency
• add deps: classify sources
• affected by remove dependency

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

Appendix: source

Thrown at internal/tracker/engine.go:1331

// 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
		}

		if fromIssue == nil || toIssue == nil {
			continue // Not found (no error) — expected if issue wasn't imported
		}

		d := &types.Dependency{
			IssueID:     fromIssue.ID,
			DependsOnID: toIssue.ID,
			Type:        types.DependencyType(dep.Type),

View on GitHub (pinned to 71377f2769)