What causes "failed to get molecule: %w" in gastownhall/beads?

Confirm the molecule root ID exists (`bd show `) and correct it.

failed to get molecule: %w

Error message

failed to get molecule: %w

What it means

`GetMoleculeProgress` starts by fetching the molecule's root issue through `r.GetIssue`; if that call fails for any reason (not-found, storage error), it wraps the result as `failed to get molecule: %w`. The molecule root must be readable before progress statistics can be assembled.

Source

Thrown at cmd/bd/mol_port.go:268

func (r uowMolReader) GetConfig(ctx context.Context, key string) (string, error) {
	return r.uw.ConfigUseCase().GetConfig(ctx, key)
}

func (r uowMolReader) IsInfraTypeCtx(ctx context.Context, t types.IssueType) bool {
	ok, err := r.uw.ConfigUseCase().IsInfraTypeCtx(ctx, t)
	return err == nil && ok
}

func (r uowMolReader) GetCustomStatusesDetailed(ctx context.Context) ([]types.CustomStatus, error) {
	return r.uw.ConfigUseCase().GetCustomStatuses(ctx)
}

func (r uowMolReader) GetMoleculeProgress(ctx context.Context, moleculeID string) (*types.MoleculeProgressStats, error) {
	stats := &types.MoleculeProgressStats{MoleculeID: moleculeID}

	root, err := r.GetIssue(ctx, moleculeID)
	if err != nil {
		return nil, fmt.Errorf("failed to get molecule: %w", err)
	}
	if root != nil {
		stats.MoleculeTitle = root.Title
	}

	dependents, err := r.GetDependentsWithMetadata(ctx, moleculeID)
	if err != nil {
		return nil, fmt.Errorf("failed to get molecule children: %w", err)
	}

	for _, dependent := range dependents {
		if dependent.DependencyType != types.DepParentChild {
			continue
		}
		stats.Total++
		switch dependent.Status {
		case types.StatusClosed:
			stats.Completed++

View on GitHub (pinned to 71377f2769)

Solutions

Confirm the molecule root ID exists (`bd show <molecule-id>`) and correct it.
Unwrap the error to see whether it was not-found (fix the ID) or a storage failure (fix the database).
List molecules (`bd mol list` or query roots) to find the correct root ID.

Example fix

// before
bd mol progress bd-999   // nonexistent molecule
// after
bd mol progress bd-100   // verified molecule root

Defensive patterns

Strategy: validation

Validate before calling

// verify the molecule root before asking for progress
bd show "$MOL_ID" --json >/dev/null 2>&1 || { echo "molecule $MOL_ID not found"; exit 1; }
bd mol progress "$MOL_ID"

Type guard

func moleculeReadable(ctx context.Context, r MolReader, id string) error {
	_, err := r.GetIssue(ctx, id)
	return err
}

Try / catch

stats, err := reader.GetMoleculeProgress(ctx, molID)
if err != nil && strings.Contains(err.Error(), "failed to get molecule") {
	return fmt.Errorf("molecule %q unreadable: %w", molID, err)
}

Prevention

Obtain molecule root IDs from listing commands, not memory.
Don't reuse root IDs after a molecule was burned or rebuilt.
Check database health when progress commands fail across many molecules.

When it happens

Trigger: `runMolCurrentProxiedServer` or `runMolProgressProxiedServer` calls `GetMoleculeProgress(ctx, moleculeID)` with an ID that cannot be resolved — the underlying `GetIssue` error (1086/1087) is re-wrapped by this `fmt.Errorf("failed to get molecule: %w", err)` line.

Common situations: Typo'd molecule ID on `bd mol progress <id>`; molecule root deleted after its children were burned; storage backend failing mid-command; pointing at a workspace that never had the molecule.

Related errors

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