gastownhall/beads · error

no database connection

Error message

no database connection

What it means

loadTemplateSubgraph requires a non-nil store implementing molReader before it can load a template epic and its descendants. If the caller passes a nil store, this guard error is thrown. It signals a programming/setup problem: the template operation ran without any database connection wired in.

Source

Thrown at cmd/bd/template.go:85

	AttachToID    string               // Molecule ID to attach spawned root to
	AttachDepType types.DependencyType // Dependency type for the attachment

	// RootOnly: if true, only create the root issue (no child step issues).
	// Used by patrol wisps where steps are inlined at prime time, not tracked as beads.
	RootOnly bool
}

// bondedIDPattern validates bonded IDs (alphanumeric, dash, underscore, dot)
var bondedIDPattern = regexp.MustCompile(`^[a-zA-Z0-9_.-]+$`)

// =============================================================================
// Beads Template Functions
// =============================================================================

// loadTemplateSubgraph loads a template epic and all its descendants
func loadTemplateSubgraph(ctx context.Context, s molReader, templateID string) (*TemplateSubgraph, error) {
	if s == nil {
		return nil, fmt.Errorf("no database connection")
	}

	// Get the root issue
	root, err := s.GetIssue(ctx, templateID)
	if err != nil {
		return nil, fmt.Errorf("failed to get template: %w", err)
	}
	if root == nil {
		return nil, fmt.Errorf("template %s not found", templateID)
	}

	subgraph := &TemplateSubgraph{
		Root:     root,
		Issues:   []*types.Issue{root},
		IssueMap: map[string]*types.Issue{root.ID: root},
	}

	// Recursively load all children (with cycle detection, GH#2719)

View on GitHub (pinned to 71377f2769)

Solutions

1. Ensure the beads database is initialized and open before running template commands (bd init; run from repo root)
2. Fix the earlier store-open failure — check for an earlier 'database not available' error in output
3. If calling the helper programmatically, pass a valid molReader store instead of nil

Example fix

// before
var s molReader // nil when store open failed but error ignored
sub, err := loadTemplateSubgraph(ctx, s, tplID)
// after
s, err := openStore(ctx)
if err != nil { return err }
sub, err := loadTemplateSubgraph(ctx, s, tplID)

s, err := openStore(ctx)
if err != nil {
    return fmt.Errorf("cannot open beads store: %w", err)
}
sub, err := loadTemplateSubgraph(ctx, s, templateID)

// guard before calling template helpers
func ensureStore(s molReader) (molReader, error) {
    if s == nil {
        return nil, fmt.Errorf("store must be opened before template operations")
    }
    return s, nil
}

sub, err := loadTemplateSubgraph(ctx, store, tplID)
if err != nil && strings.Contains(err.Error(), "no database connection") {
    return fmt.Errorf("template operation skipped: store not initialized; run bd init first")
}

When it happens

Trigger: Any template command path (deleteProtoSubgraph, bondProtoMolWithSubgraph, bondProtoMolAttachInto, resolveOrCookToSubgraph, burnMultipleMolecules, burnWispMolecule) reaching loadTemplateSubgraph with s == nil — i.e. the store failed to open earlier or was not propagated to the template layer.

Common situations: Database unavailable earlier in the command but the error was swallowed or defaulted to nil; calling template helper APIs programmatically without opening the store first; running before bd init in a workspace.

Related errors

• failed to open target store for dry-run: %w
• no database connection available (%s)
• no database — run 'bd init' or 'bd bootstrap' first
• unable to find orphaned issues: %w
• missing required variables: %s

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