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

Unwrap the error and address the underlying dependent-query failure (storage health, locks).

failed to get molecule children: %w

Error message

failed to get molecule children: %w

What it means

After loading the root, `GetMoleculeProgress` fetches the molecule's children via `GetDependentsWithMetadata`. If that dependent-lookup fails, the error is wrapped as `failed to get molecule children: %w`, indicating the molecule root was fine but enumerating its child dependencies failed.

Source

Thrown at cmd/bd/mol_port.go:276

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++
		case types.StatusInProgress:
			stats.InProgress++
			if stats.CurrentStepID == "" {
				stats.CurrentStepID = dependent.ID
			}
		}
	}
	return stats, nil

View on GitHub (pinned to 71377f2769)

Solutions

Unwrap the error and address the underlying dependent-query failure (storage health, locks).
Run `bd doctor` and, if needed, re-sync (`bd dolt pull`) to repair dependency data.
Retry the command — transient lock contention during concurrent writes commonly causes this.

Example fix

// before
stats, err := reader.GetMoleculeProgress(ctx, molID) // opaque child failure
// after
stats, err := reader.GetMoleculeProgress(ctx, molID)
if err != nil {
    log.Printf("children query failed: %v", errors.Unwrap(err))
}

Defensive patterns

Strategy: retry

Validate before calling

// pre-check dependency data integrity
bd doctor --json | jq -e '.healthy' >/dev/null || exit 1
bd mol progress "$MOL_ID" --json >/dev/null 2>&1 || { echo "children query failing; resync?"; bd dolt pull; }

Try / catch

var stats *types.MoleculeProgressStats
var err error
for i := 0; i < 3; i++ {
	stats, err = reader.GetMoleculeProgress(ctx, molID)
	if err == nil || !strings.Contains(err.Error(), "molecule children") {
		break
	}
	time.Sleep(time.Duration(1<<i) * 100 * time.Millisecond) // transient lock retry
}

Prevention

Avoid heavy concurrent writes while reading molecule progress.
Run `bd doctor` / resync after abnormal shutdowns to keep dependency tables consistent.
Bound retries and surface the unwrapped cause if failures persist.

When it happens

Trigger: `runMolCurrentProxiedServer` or `runMolProgressProxiedServer` requests progress for a molecule whose root resolves but whose dependents query errors out — dependency-table read failures, storage errors, or transaction issues inside `GetDependentsWithMetadata`, wrapped at the `fmt.Errorf("failed to get molecule children: %w", err)` line.

Common situations: Corrupted or partially-synced dependency tables; database lock/IO errors under concurrent writes; a very large molecule hitting query timeouts; schema drift after a version upgrade.

Related errors

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