gastownhall/beads · error

loading formula %q: %w

Error message

loading formula %q: %w

What it means

The shared resolve-and-cook helper (`resolveAndCookFormulaWithVars`, used by pour, wisp, mol bond/seed, verify) wraps `parser.LoadByName` failures as `loading formula %q`. The named formula could not be found in any search path, could not be read, or failed to parse. This is the entry-point failure for every formula-name-based command.

Source

Thrown at cmd/bd/cook.go:709

// resolveAndCookFormula loads a formula by name, resolves it, applies all transformations,
// and returns an in-memory TemplateSubgraph ready for instantiation.
// This is the main entry point for ephemeral proto cooking.
func resolveAndCookFormula(formulaName string, searchPaths []string) (*TemplateSubgraph, error) {
	return resolveAndCookFormulaWithVars(formulaName, searchPaths, nil)
}

// resolveAndCookFormulaWithVars loads a formula and optionally filters steps by condition.
// If conditionVars is provided, steps with conditions that evaluate to false are excluded.
// Pass nil for conditionVars to include all steps (condition filtering skipped).
func resolveAndCookFormulaWithVars(formulaName string, searchPaths []string, conditionVars map[string]string) (*TemplateSubgraph, error) {
	// Create parser with search paths
	parser := formula.NewParser(searchPaths...)

	// Load formula by name
	f, err := parser.LoadByName(formulaName)
	if err != nil {
		return nil, fmt.Errorf("loading formula %q: %w", formulaName, err)
	}

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

	// Validate any caller-provided variable values against enum/pattern/
	// required-empty constraints. This is deliberately presence-agnostic:
	// a var missing entirely is left to the caller's own UX (e.g. bd mol
	// pour/wisp's missing-var hint), but a var explicitly provided with a
	// value that violates its constraints must error here so it reaches
	// every caller of this shared path (pour, wisp, mol bond, mol seed) —
	// runCook does not go through this helper; it validates separately via
	// its own formula.ValidateVars call under --mode=runtime. Previously
	// only that `bd cook --mode=runtime` path enforced these (mybd-u2r6).
	if conditionVars != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the formula name spelling against the actual file names in your formula directories
2. Run from the repo root or pass the correct search path (e.g. `--path .formula`) so the parser can find the file
3. Run `bd formula list` to see which formulas are discoverable
4. If the file exists, fix the syntax error reported by the wrapped parser error

Example fix

// before
bd mol pour deploy-pipline
// after
bd mol pour deploy-pipeline

p := formula.NewParser(searchPaths...)
if _, err := p.LoadByName(name); err != nil {
    return fmt.Errorf("formula %q unresolvable in %v: %w", name, searchPaths, err)
}

if err != nil {
    if errors.Is(err, os.ErrNotExist) {
        // formula file missing: fix name or add search path
    }
    return fmt.Errorf("loading formula %q: %w", name, err)
}

When it happens

Trigger: `bd mol pour`, `bd mol wisp`, `bd mol bond`, `bd mol seed`, or verify paths called with a formula name that does not resolve: wrong name, formula file absent from search paths (`--path` flags / default directories), unreadable file, or YAML parse error.

Common situations: Typos in formula names on the command line; running from a directory outside the formula search paths; formula defined only in another repo; recent rename of a formula file; missing file extension or malformed front matter breaking the parser.

Related errors

• parsing formula: %w
• loading aspect %q: %w
• runtime mode requires all variables to have values Missing:
• reading source: %w
• formula %q not accessible: %w

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