gastownhall/beads · error

loading aspect %q: %w

Error message

loading aspect %q: %w

What it means

`bd cook` wraps any failure from loading an aspect formula referenced in `compose.aspects`. The formula parser (`parser.LoadByName`) searches the configured search paths and fails (file not found, parse error, or I/O error); cook re-raises it with the aspect name for context. Aspects must load successfully before their advice can be applied to the resolved steps.

Source

Thrown at cmd/bd/cook.go:206

		return nil, fmt.Errorf("applying inline expansions: %w", err)
	}
	resolved.Steps = inlineExpandedSteps

	// Apply expansion operators
	if resolved.Compose != nil && (len(resolved.Compose.Expand) > 0 || len(resolved.Compose.Map) > 0) {
		expandedSteps, err := formula.ApplyExpansions(resolved.Steps, resolved.Compose, parser)
		if err != nil {
			return nil, fmt.Errorf("applying expansions: %w", err)
		}
		resolved.Steps = expandedSteps
	}

	// Apply aspects from compose.aspects
	if resolved.Compose != nil && len(resolved.Compose.Aspects) > 0 {
		for _, aspectName := range resolved.Compose.Aspects {
			aspectFormula, err := parser.LoadByName(aspectName)
			if err != nil {
				return nil, fmt.Errorf("loading aspect %q: %w", aspectName, err)
			}
			if aspectFormula.Type != formula.TypeAspect {
				return nil, fmt.Errorf("%q is not an aspect formula (type=%s)", aspectName, aspectFormula.Type)
			}
			if len(aspectFormula.Advice) > 0 {
				resolved.Steps = formula.ApplyAdvice(resolved.Steps, aspectFormula.Advice)
			}
		}
	}

	return resolved, nil
}

// outputCookDryRun displays a dry-run preview of what would be cooked
func outputCookDryRun(resolved *formula.Formula, protoID string, runtimeMode bool, inputVars map[string]string, vars, bondPoints []string) {
	modeLabel := "compile-time"
	if runtimeMode {
		modeLabel = "runtime"

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the aspect name in the formula's `compose.aspects` against the actual aspect file name (typos are the top cause)
2. Run `bd formula list` (or inspect the formula search paths) to confirm the aspect file exists in one of the search directories
3. Create the missing aspect formula file, or remove the aspect from `compose.aspects` if it is no longer needed
4. If the aspect file exists but fails to parse, fix the YAML/front-matter syntax error reported by the wrapped error

Example fix

// before (compose.aspects in formula)
aspects: [asapect-review]
// after
aspects: [aspect-review]

for _, a := range formulaComposeAspects {
    if _, err := os.Stat(filepath.Join(formulaDir, a+".formula.yml")); err != nil {
        return fmt.Errorf("aspect %q not found in %s", a, formulaDir)
    }
}

if err != nil {
    var nf *os.PathError
    if errors.As(err, &nf) { /* aspect file missing: fix name or path */ }
    return fmt.Errorf("loading aspect %q: %w", aspectName, err)
}

When it happens

Trigger: Running `bd cook` on a formula whose `compose.aspects` list names an aspect that `parser.LoadByName` cannot load: aspect file missing from search paths, typo in aspect name, missing `.formula` extension resolution, or unreadable/corrupt aspect file.

Common situations: Hand-written formula YAML referencing an aspect that was never created; copying a formula between repos where aspect search paths differ; renaming an aspect file without updating `compose.aspects`; permission or symlink issues in the formula search directories.

Related errors

• parsing formula: %w
• %q is not an aspect formula (type=%s)
• loading formula %q: %w
• reading source: %w
• inline expand on step %q: loading %q: %w

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