gastownhall/beads · error

template %s not found

Error message

template %s not found

What it means

loadTemplateSubgraph loads a template root issue and its dependency subgraph. It first fetches the root issue by ID via s.GetIssue; if the storage layer returns nil issue with no error (i.e. the ID simply does not exist), it throws 'template %s not found'. This distinguishes a missing template from a storage failure, which would surface as 'failed to get template: %w' instead.

Source

Thrown at cmd/bd/template.go:94

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)
	visited := map[string]bool{root.ID: true}
	if err := loadDescendants(ctx, s, subgraph, root.ID, visited); err != nil {
		return nil, err
	}

	// Load all dependencies within the subgraph
	for _, issue := range subgraph.Issues {
		deps, err := s.GetDependencyRecords(ctx, issue.ID)
		if err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd list` or search protos (issues labeled with the template label) to find the correct template ID and retry with the exact ID.
2. If you only know the title, use the resolution path (resolveProtoIDOrTitle) which also matches by title.
3. Check you are operating in the correct repository/database (.beads directory) that actually contains the template.
4. If the template was deleted intentionally, recreate it before retrying the operation.

Example fix

// before
sub, err := instantiateFromTemplate(ctx, s, "bd-wrong-id", vars)
// after
id, err := resolveProtoIDOrTitle(ctx, s, "my-proto-title") // resolve first
if err != nil { return err }
sub, err := instantiateFromTemplate(ctx, s, id, vars)

root, err := s.GetIssue(ctx, templateID)
if err != nil { return err }
if root == nil { return fmt.Errorf("template %q does not exist; list protos first", templateID) }

func templateExists(ctx context.Context, s storage.DoltStorage, id string) bool {
	iss, err := s.GetIssue(ctx, id)
	return err == nil && iss != nil
}

sub, err := loadTemplateSubgraph(ctx, s, id)
if err != nil {
	if strings.Contains(err.Error(), "not found") {
		// prompt user to pick from available protos
	}
	return err
}

When it happens

Trigger: Calling any proto-molecule operation (deleteProtoSubgraph, bondProtoMolWithSubgraph, bondProtoMolAttachInto, resolveOrCookToSubgraph, burnMultipleMolecules, burnWispMolecule) with a template ID that does not exist in the database — e.g. a typo'd ID, an ID from another repo/database, or a template that was already deleted.

Common situations: Running `bd mol pour <name>` or burn/delete commands after the proto was deleted or renamed; referencing a template ID copied from documentation of a different project; stale shell history after switching databases (different .beads directory).

Related errors

• no proto found matching %q (by ID or title)
• no store is open for this workspace
• resolving ID %s: %w
• resolving ID %s: no issue found matching %q
• resolving --deps target %q: %w

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