What causes "loading proto: %w" in gastownhall/beads?

Inspect the wrapped cause for the specific failing step or issue ID

loading proto: %w

Error message

loading proto: %w

What it means

After validating that the resolved issue is a proto, bd mol pour loads its template subgraph (the proto plus its dependent child issues) with loadTemplateSubgraph. This error wraps any failure of that traversal, preserving the cause. It means the proto exists and is labeled correctly but its dependency graph could not be loaded — typically a storage failure or an inconsistent/corrupt dependency graph.

Source

Thrown at cmd/bd/mol_proxied_server.go:72

		subgraph := formulaSubgraph
		protoID := formulaProtoID
		if subgraph == nil {
			resolvedID, err := utils.ResolvePartialID(ctx, w, in.protoArg)
			if err != nil {
				return pourProxiedResult{}, "", fmt.Errorf("%s not found as formula or proto ID", in.protoArg)
			}
			protoID = resolvedID
			protoIssue, err := w.GetIssue(ctx, protoID)
			if err != nil {
				return pourProxiedResult{}, "", fmt.Errorf("loading proto %s: %w", protoID, err)
			}
			if !isProto(protoIssue) {
				return pourProxiedResult{}, "", fmt.Errorf("%s is not a proto (missing '%s' label)", protoID, MoleculeLabel)
			}
			subgraph, err = loadTemplateSubgraph(ctx, w, protoID)
			if err != nil {
				return pourProxiedResult{}, "", fmt.Errorf("loading proto: %w", err)
			}
		}

		type attachmentInfo struct {
			id       string
			issue    *types.Issue
			subgraph *TemplateSubgraph
		}
		var attachments []attachmentInfo
		for _, attachArg := range in.attachArgs {
			attachID, err := utils.ResolvePartialID(ctx, w, attachArg)
			if err != nil {
				return pourProxiedResult{}, "", fmt.Errorf("resolving attachment ID %s: %w", attachArg, err)
			}
			attachIssue, err := w.GetIssue(ctx, attachID)
			if err != nil {
				return pourProxiedResult{}, "", fmt.Errorf("loading attachment %s: %w", attachID, err)
			}

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped cause for the specific failing step or issue ID
Run bd doctor to detect and repair dangling dependencies/corruption
Re-add or remove the orphaned dependency edge, then retry the pour
Re-create the proto from its formula if the template graph is unrecoverable

Example fix

// before: hard failure on one bad edge
subgraph, err := loadTemplateSubgraph(ctx, w, protoID)
if err != nil { return fmt.Errorf("loading proto: %w", err) }
// after: surface the offending dependent ID for repair
subgraph, err := loadTemplateSubgraph(ctx, w, protoID)
if err != nil {
	log.Printf("check dependencies of %s (bd doctor)", protoID)
	return fmt.Errorf("loading proto: %w", err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// sanity-check the template graph before pouring
deps, err := reader.GetDependentsWithMetadata(ctx, protoID)
if err != nil {
	return fmt.Errorf("template graph for %s unreadable: %w", protoID, err)
}
for _, d := range deps {
	if _, err := reader.GetIssue(ctx, d.ID); err != nil {
		return fmt.Errorf("orphaned dependency on %s", d.ID)
	}
}

Try / catch

err := pourCmd(protoID)
if err != nil && strings.HasPrefix(err.Error(), "loading proto:") {
	// run `bd doctor` to detect dangling deps / corruption, then retry
}

Prevention

Run bd doctor regularly to catch dangling dependencies
Delete dependents properly (let bd clean up edges) instead of raw DB edits
Avoid interrupting molecule writes mid-transaction
Keep templates modest in size to avoid traversal timeouts

When it happens

Trigger: Calling `bd mol pour <protoID>` where loadTemplateSubgraph fails: database errors while reading dependents, a dependency edge pointing to a missing/deleted issue, graph cycles or corrupt dependency rows, or context cancellation mid-traversal.

Common situations: A child issue of the proto was deleted without removing the dependency edge (orphaned dependency); database corruption after an interrupted write; very large templates hitting timeouts; sync conflicts producing dangling dependency records.

Related errors

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