gastownhall/beads · error

swarm molecule '%s' has no linked epic

Error message

swarm molecule '%s' has no linked epic

What it means

Thrown when a swarm molecule's dependency records contain no DepRelatesTo edge, so no linked epic could be identified. This is a data-model invariant error: every swarm molecule must relate-to exactly one epic.

Source

Thrown at cmd/bd/swarm_proxied_server.go:144

		var epic *types.Issue

		if issue.IssueType == "molecule" && issue.MolType == types.MolTypeSwarm {
			deps, err := r.GetDependencyRecords(ctx, issue.ID)
			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 {

View on GitHub (pinned to 71377f2769)

Solutions

1. Add the missing link: `bd dep add <molecule-id> <epic-id> --type relates-to`
2. Verify existing deps with `bd dep list <molecule-id>`
3. Recreate the molecule under the correct epic instead of repairing the link

Example fix

// before (molecule created without epic link)
bd mol create my-swarm --type swarm
// after
bd mol create my-swarm --type swarm
bd dep add bd-123 bd-100 --type relates-to

// check a swarm molecule has a relates-to dep before invoking swarm
hasEpic := false
for _, dep := range deps {
    if dep.Type == "relates-to" { hasEpic = true }
}
if !hasEpic {
    return fmt.Errorf("molecule %s has no linked epic; run: bd dep add %s <epic> --type relates-to", id, id)
}

func isSwarmMoleculeLinked(issue *types.Issue, deps []types.Dependency) bool {
    if issue.IssueType != "molecule" || issue.MolType != types.MolTypeSwarm {
        return false
    }
    for _, d := range deps {
        if d.Type == types.DepRelatesTo { return true }
    }
    return false
}

When it happens

Trigger: Creating a molecule with MolType=MolTypeSwarm but never adding a relates-to dependency to an epic; the relates-to dep was deleted; or the deps loop filtered out all rows because dep.Type never matched types.DepRelatesTo.

Common situations: Hand-editing issue JSONL exports and dropping the dependency; older bd versions or scripts that create swarm molecules without linking; a sync conflict that dropped the dependency row.

Related errors

• failed to get swarm dependencies: %v
• failed to get linked epic: %v
• '%s' is not an epic or swarm molecule (type: %s)
• failed to get swarm status: %v
• recompute-blocked: %w

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