gastownhall/beads · error

parsing formula: %w

Error message

parsing formula: %w

What it means

In cmd/bd/cook.go:163, loadAndResolveFormula wraps any error from loading a formula after both lookup strategies fail: parser.LoadByName (searching the .beads/formulas/ registry by name) and, on that failure, parser.ParseFile (treating the argument as a file path). The %w keeps the underlying cause (file not found, YAML/JSON syntax error, schema mismatch) visible via errors.Is/As. It signals that the formula could not be turned into an in-memory Formula at all, before any inheritance resolution runs.

Source

Thrown at cmd/bd/cook.go:163

		inputVars:   inputVars,
		runtimeMode: runtimeMode,
		formulaPath: args[0],
	}, nil
}

// loadAndResolveFormula parses a formula file and applies all transformations.
// It first tries to load by name from the formula registry (.beads/formulas/),
// and falls back to parsing as a file path if that fails.
func loadAndResolveFormula(formulaPath string, searchPaths []string) (*formula.Formula, error) {
	parser := formula.NewParser(searchPaths...)

	// Try to load by name first (from .beads/formulas/ registry)
	f, err := parser.LoadByName(formulaPath)
	if err != nil {
		// Fall back to parsing as a file path
		f, err = parser.ParseFile(formulaPath)
		if err != nil {
			return nil, fmt.Errorf("parsing formula: %w", err)
		}
	}

	// Resolve inheritance
	resolved, err := parser.Resolve(f)
	if err != nil {
		return nil, fmt.Errorf("resolving formula: %w", err)
	}

	// Apply control flow operators - loops, branches, gates
	controlFlowSteps, err := formula.ApplyControlFlow(resolved.Steps, resolved.Compose)
	if err != nil {
		return nil, fmt.Errorf("applying control flow: %w", err)
	}
	resolved.Steps = controlFlowSteps

	// Apply advice transformations
	if len(resolved.Advice) > 0 {

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the name exists in the registry: list .beads/formulas/ and confirm the file (or pass an explicit path, e.g. `bd cook .beads/formulas/<name>.md`).
2. Run the underlying cause to ground: the wrapped error says 'no such file' vs 'parse' — fix the path or the YAML syntax accordingly.
3. Validate the formula file structure (required frontmatter/fields) with `bd formula show <name>` or by parsing it in a scratch call.
4. Sync/pull the repository so the .beads/formulas/ registry contains the expected formula.

Example fix

// before
cmd := exec.Command("bd", "cook", "fix-bug") // formula not in .beads/formulas/
// after
cmd := exec.Command("bd", "cook", ".beads/formulas/fix-bug.md") // or commit the formula to .beads/formulas/

func formulaLoadable(nameOrPath string) error {
	if _, err := parser.LoadByName(nameOrPath); err == nil {
		return nil
	}
	if fi, err := os.Stat(nameOrPath); err != nil || fi.IsDir() {
		return fmt.Errorf("formula %q not found in .beads/formulas/ and not a file", nameOrPath)
	}
	_, err := parser.ParseFile(nameOrPath)
	return err
}

func formulaExists(nameOrPath string) bool {
	if _, err := parser.LoadByName(nameOrPath); err == nil {
		return true
	}
	fi, err := os.Stat(nameOrPath)
	return err == nil && !fi.IsDir()
}

f, err := loadAndResolveFormula(p)
if err != nil {
	var pe *fs.PathError
	if errors.As(err, &pe) {
		return fmt.Errorf("formula %q not found: check name in .beads/formulas/ or path", p)
	}
	return fmt.Errorf("invalid formula %q: %w", p, err) // parse error branch
}

When it happens

Trigger: Calling `bd cook <formula>` where the formula name does not exist in .beads/formulas/ AND the string is not a readable, well-formed formula file: nonexistent path, typo'd name, malformed YAML/frontmatter, missing required fields (steps, title), or a file the current user cannot read.

Common situations: Typo in the formula name or path; running bd from a directory where .beads/formulas/ was never populated or is gitignored; a teammate's formula file not yet pulled; editing a formula file and introducing a YAML syntax error; using a relative path from the wrong working directory.

Related errors

• loading formula %q: %w
• line %d: %w
• line %d: 'dep' requires a subcommand (add|remove)
• line %d: unknown dep subcommand %q (want add|remove)
• line %d: unsupported batch command %q (supported: close, upd

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