gastownhall/beads · error

epic '%s' not found: %v

Error message

epic '%s' not found: %v

What it means

Error from runSwarmValidateProxiedServer in cmd/bd/swarm_proxied_server.go:49. It fires when utils.ResolvePartialID cannot turn the user-supplied argument (full ID or partial prefix) into a concrete issue ID while running `bd swarm validate` in proxied-server mode. The original resolver error is appended after the colon. This is a user-input resolution failure, not a storage fault.

Source

Thrown at cmd/bd/swarm_proxied_server.go:49

	evt := metrics.NewCommandEvent("swarm-validate")
	defer func() {
		if c := metrics.Global(); c != nil {
			c.CloseEventAndAdd(evt)
		}
	}()

	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 {

View on GitHub (pinned to 71377f2769)

Solutions

  1. Run `bd list` (or `bd show <full-id>`) to confirm the exact epic ID.
  2. Use the full issue ID instead of a prefix to avoid ambiguity.
  3. If the issue exists elsewhere, point the command at the right repo/database or sync with `bd dolt pull`.
  4. Check the text after the colon for resolver-level causes (e.g. multiple matches) and disambiguate.

Example fix

// before
bd swarm validate bd-12   // ambiguous prefix

// after
bd swarm validate bd-1234
Defensive patterns

Strategy: validation

Validate before calling

bd show bd-1234 >/dev/null 2>&1 && bd swarm validate bd-1234 || echo "resolve the full ID first: bd list"

Try / catch

if err != nil && strings.Contains(err.Error(), "not found") {
    // fall back to bd list and pick the exact ID
}

Prevention

When it happens

Trigger: `bd swarm validate <prefix>` in proxied-server mode where the prefix matches no issue, is ambiguous (matches multiple), or the resolver's underlying lookup call fails.

Common situations: Typo in the epic ID; passing a short prefix that matches several issues; the epic lives in another repo/database not visible to the proxied server; issue was deleted or closed and pruned.

Related errors

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