gastownhall/beads · error

'%s' is not an epic or swarm molecule (type: %s)

Error message

'%s' is not an epic or swarm molecule (type: %s)

What it means

Thrown when the requested issueID is neither an epic nor a molecule — the swarm command only operates on epics and swarm molecules. The message includes the actual IssueType for diagnosis.

Source

Thrown at cmd/bd/swarm_proxied_server.go:149

			if err != nil {
				return nil, fmt.Errorf("failed to get swarm dependencies: %v", err)
			}
			for _, dep := range deps {
				if dep.Type == types.DepRelatesTo {
					epic, err = uw.IssueUseCase().GetIssue(ctx, dep.DependsOnID)
					if err != nil {
						return nil, fmt.Errorf("failed to get linked epic: %v", err)
					}
					break
				}
			}
			if epic == nil {
				return nil, fmt.Errorf("swarm molecule '%s' has no linked epic", issueID)
			}
		} else if issue.IssueType == types.TypeEpic || issue.IssueType == "molecule" {
			epic = issue
		} else {
			return nil, fmt.Errorf("'%s' is not an epic or swarm molecule (type: %s)", issueID, issue.IssueType)
		}

		status, err := getSwarmStatus(ctx, r, epic)
		if err != nil {
			return nil, fmt.Errorf("failed to get swarm status: %v", err)
		}
		return status, nil
	})
	if err != nil {
		return HandleErrorRespectJSON("%v", err)
	}

	if jsonOutput {
		return outputJSON(status)
	}

	renderSwarmStatus(status)
	return nil

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm the issue type with `bd show <issueID>` and use an epic or swarm molecule ID instead
2. If it should be an epic, set its type: `bd update <issueID> --type epic`
3. For molecule types, recreate with `bd mol create` so IssueType/MolType are set correctly

Example fix

// before
bd swarm bd-456        // bd-456 is a plain task
// after
bd swarm bd-100        // bd-100 is the epic
bd swarm bd-456-m      // or its swarm molecule

// check the issue type before invoking the swarm command
if issue.IssueType != "epic" && issue.IssueType != "molecule" {
    return fmt.Errorf("%s is a %s; swarm requires an epic or swarm molecule", issueID, issue.IssueType)
}

func isSwarmTarget(issue *types.Issue) bool {
    return issue.IssueType == types.TypeEpic || issue.IssueType == "molecule"
}

When it happens

Trigger: Passing a plain task/bug/feature ID to the swarm status command; passing an ID that exists but has IssueType set to something other than epic or molecule (e.g. a chore or a raw task).

Common situations: Typo or copy/paste of the wrong issue ID into `bd swarm <id>`; assuming any issue works with the swarm command; legacy issues created before molecule typing existed.

Related errors

• failed to get swarm dependencies: %v
• failed to get linked epic: %v
• swarm molecule '%s' has no linked epic
• failed to get swarm status: %v
• no store is open for this workspace

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