What causes "failed to analyze epic: %v" in gastownhall/beads?

Look at the full error chain to find the real cause (usually a per-child dependency-read failure).

failed to analyze epic: %v

Error message

failed to analyze epic: %v

What it means

Error from runSwarmValidateProxiedServer in cmd/bd/swarm_proxied_server.go:68. Wraps any failure returned by analyzeEpicForSwarm — the graph-building pass over the epic's children (dependency reads, cycle/front analysis). Any wrapped storage error inside the analysis bubbles up under this prefix. It is printed via HandleErrorRespectJSON, honoring --json output mode.

Source

Thrown at cmd/bd/swarm_proxied_server.go:68

		}

		epic, err := uw.IssueUseCase().GetIssue(ctx, epicID)
		if gateProxiedNotFound(err) || (err == nil && epic == nil) {
			// Classic reports a nil epic after a successful resolve this way;
			// keep the message for parity.
			return nil, fmt.Errorf("epic '%s' not found", epicID)
		}
		if err != nil {
			return nil, fmt.Errorf("failed to get epic: %v", err)
		}

		if epic.IssueType != types.TypeEpic && epic.IssueType != "molecule" {
			return nil, fmt.Errorf("'%s' is not an epic or molecule (type: %s)", epicID, epic.IssueType)
		}

		analysis, err := analyzeEpicForSwarm(ctx, r, epic)
		if err != nil {
			return nil, fmt.Errorf("failed to analyze epic: %v", err)
		}
		return analysis, nil
	})
	if err != nil {
		return HandleErrorRespectJSON("%v", err)
	}

	if !verbose {
		analysis.Issues = nil
	}

	if jsonOutput {
		if jerr := outputJSON(analysis); jerr != nil {
			return jerr
		}
		if !analysis.Swarmable {
			return SilentExit()
		}

View on GitHub (pinned to 71377f2769)

Solutions

Look at the full error chain to find the real cause (usually a per-child dependency-read failure).
Check the named child issue with `bd show <child-id>` and repair or recreate its dependencies if corrupt.
Re-run when no other bd process is writing to avoid lock contention.
Run `bd doctor`; restore/sync the database if corruption is detected.

Defensive patterns

Strategy: try-catch

Validate before calling

bd doctor || echo "database unhealthy before swarm validate"

Try / catch

if err != nil && strings.Contains(err.Error(), "failed to analyze epic") {
    // drill into the wrapped cause; usually a per-child dependency read failure
}

Prevention

Run swarm analysis when no other bd process is writing
Keep the database healthy with periodic bd doctor checks
Repair corrupt dependency records as soon as they surface

When it happens

Trigger: `bd swarm validate <epic>` in proxied-server mode when analyzeEpicForSwarm errors — typically a GetDependencyRecords failure on one of the children (see the "failed to get dependencies for %s" wrap inside it).

Common situations: Storage flakiness mid-analysis; a corrupted dependency row for one child; database lock contention from a concurrent bd process writing during the read transaction.

Related errors

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