gastownhall/beads · error

no proto found matching %q (by ID or title)

Error message

no proto found matching %q (by ID or title)

What it means

resolveProtoIDOrTitle exhausts both resolution strategies — exact ID lookup and title search — without a single matching proto. When the matches list is empty it throws 'no proto found matching %q (by ID or title)'. This is a user-input/resolution error: the requested template simply does not exist under that ID or title.

Source

Thrown at cmd/bd/template.go:297

	for _, proto := range protos {
		// Check for exact title match (case-insensitive)
		if strings.EqualFold(proto.Title, input) {
			exactMatch = proto
			break
		}
		// Check for partial title match (case-insensitive)
		if strings.Contains(strings.ToLower(proto.Title), strings.ToLower(input)) {
			matches = append(matches, proto)
		}
	}

	if exactMatch != nil {
		return exactMatch.ID, nil
	}

	if len(matches) == 0 {
		return "", fmt.Errorf("no proto found matching %q (by ID or title)", input)
	}

	if len(matches) == 1 {
		return matches[0].ID, nil
	}

	// Multiple matches - show them all for disambiguation
	var matchNames []string
	for _, m := range matches {
		matchNames = append(matchNames, fmt.Sprintf("%s: %s", m.ID, m.Title))
	}
	return "", fmt.Errorf("ambiguous: %q matches %d protos:\n  %s\nUse the ID or a more specific title", input, len(matches), strings.Join(matchNames, "\n  "))
}

// extractVariables finds all {{variable}} patterns in text.
// Handlebars control keywords like "else", "this" are excluded.
func extractVariables(text string) []string {
	matches := variablePattern.FindAllStringSubmatch(text, -1)

View on GitHub (pinned to 71377f2769)

Solutions

1. List existing protos to see available templates and copy the exact ID or title.
2. Verify the proto actually has the template label; re-add it if a manual edit stripped it.
3. Check you are in the repository that owns the proto (each repo has its own .beads database).
4. Create the proto first if it does not exist yet, then retry.

Example fix

// before
bd mol pour "My Molecuel"  // typo
// after
bd mol pour "My Molecule"  // exact title, or use the proto ID

// before invoking any proto command:
protos, _ := s.GetIssuesByLabel(ctx, BeadsTemplateLabel)
for _, p := range protos { fmt.Println(p.ID, p.Title) } // confirm exact match exists

pid, err := resolveProtoIDOrTitle(ctx, s, input)
if err != nil && strings.Contains(err.Error(), "no proto found matching") {
	// surface available protos to the user
	return fmt.Errorf("%w; run protos list to see options", err)
}

When it happens

Trigger: Passing a title or partial ID to a proto-consuming command (spawn/bond/cook/burn flows that call resolveProtoIDOrTitle) where no issue labeled as a template matches either by ID or by title.

Common situations: Typo in molecule name; the proto lives in a different repo/.beads database; the proto was created without the template label so it is invisible to the search; casing/wording mismatch in the title.

Related errors

• template %s not found
• ambiguous: %q matches %d protos: %s Use the ID or a more s
• resolving ID %s: no issue found matching %q
• resolving --deps target %q: %w
• parent issue %s not found

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