What causes "epic '%s' not found" in gastownhall/beads?

Verify the issue exists: `bd show `.

epic '%s' not found

Error message

epic '%s' not found

What it means

Error from runSwarmValidateProxiedServer in cmd/bd/swarm_proxied_server.go:56. Raised when the epic ID resolved successfully but GetIssue returns a proxied not-found signal or a nil issue with nil error. The comment in source notes this mirrors classic-mode parity: resolution found a candidate that does not actually exist as a readable issue.

Source

Thrown at cmd/bd/swarm_proxied_server.go:56

	verbose, _ := cmd.Flags().GetBool("verbose")

	if uowProvider == nil {
		return HandleErrorRespectJSON("proxied-server UOW provider not initialized")
	}

	analysis, err := uow.RunTxRead(ctx, uowProvider, func(ctx context.Context, uw uow.UnitOfWork) (*SwarmAnalysis, error) {
		r := uowMolReader{uw: uw}

		epicID, err := utils.ResolvePartialID(ctx, r, args[0])
		if err != nil {
			return nil, fmt.Errorf("epic '%s' not found: %v", args[0], err)
		}

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

View on GitHub (pinned to 71377f2769)

Solutions

Verify the issue exists: `bd show <id>`.
Re-sync the database: `bd dolt pull` (the row may be missing locally).
If the epic was deleted intentionally, pick the correct current epic ID.
If sync is broken, check the git remote refs/dolt data and push/pull to repair.

Defensive patterns

Strategy: validation

Validate before calling

bd show "$EPIC_ID" >/dev/null 2>&1 || echo "epic missing locally; run bd dolt pull"

Try / catch

if err != nil && strings.HasSuffix(err.Error(), "not found") {
    // verify with bd show, re-sync, then retry
}

Prevention

Sync before validating epics created on other machines
Never assume an ID seen in an old plan still exists — check bd show
Watch for concurrent deletes when scripting

When it happens

Trigger: `bd swarm validate <id>` in proxied-server mode where ResolvePartialID succeeded but uw.IssueUseCase().GetIssue(ctx, epicID) reports not-found (gateProxiedNotFound) or returns (nil, nil).

Common situations: Stale ID from another machine or a deleted issue; partially synced database where the ID index knows the prefix but the issue row is absent; race where the epic was removed between listing and validate.

Related errors

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