What causes "map: loading %q: %w" in gastownhall/beads?

Fix the formula name in the map rule's `with:` to match an existing expansion formula

map: loading %q: %w

Error message

map: loading %q: %w

What it means

Wraps the error from parser.LoadByName while loading the formula referenced by a compose `map` rule. The formula name in `with:` could not be resolved or failed to load/parse; the underlying loader error is preserved.

Source

Thrown at internal/formula/expand.go:109

		expanded[rule.Target] = true

		// Update dependencies: any step that depended on the target should now
		// depend on the last step of the expansion
		if len(expandedSteps) > 0 {
			lastStepID := expandedSteps[len(expandedSteps)-1].ID
			result = UpdateDependenciesForExpansion(result, rule.Target, lastStepID)
		}

		// Rebuild stepMap from result so subsequent iterations see resolved deps
		stepMap = buildStepMap(result)
	}

	// Apply map rules (pattern matching)
	for _, rule := range compose.Map {
		// Load the expansion formula
		expFormula, err := parser.LoadByName(rule.With)
		if err != nil {
			return nil, fmt.Errorf("map: loading %q: %w", rule.With, err)
		}

		if expFormula.Type != TypeExpansion {
			return nil, fmt.Errorf("map: %q is not an expansion formula (type=%s)", rule.With, expFormula.Type)
		}

		if len(expFormula.Template) == 0 {
			return nil, fmt.Errorf("map: %q has no template steps", rule.With)
		}

		// Merge formula default vars with rule overrides
		vars := mergeVars(expFormula, rule.Vars)

		// Find all matching steps (including nested children)
		// Rebuild stepMap to capture any changes from previous expansions
		stepMap = buildStepMap(result)
		var toExpand []*Step
		for id, step := range stepMap {

View on GitHub (pinned to 71377f2769)

Solutions

Fix the formula name in the map rule's `with:` to match an existing expansion formula
Ensure the formula file exists in a registered formula search path
Fix syntax/parse errors reported in the wrapped loader error

Example fix

# before
map:
  - select: "gen-*"
    with: matrix_expan  # typo
# after
map:
  - select: "gen-*"
    with: matrix-expand

Defensive patterns

Strategy: validation

Validate before calling

for _, rule := range compose.Map {
    if _, err := parser.LoadByName(rule.With); err != nil {
        return fmt.Errorf("map rule with=%q cannot load: %w", rule.With, err)
    }
}

Type guard

func formulaExists(name string) bool { _, err := parser.LoadByName(name); return err == nil }

Try / catch

expanded, err := formula.ApplyExpansions(steps, compose)
if err != nil && strings.Contains(err.Error(), "map: loading") {
    return fmt.Errorf("check map rule `with:` names and formula search paths: %w", err)
}

Prevention

Keep formula names consistent (kebab-case, single convention)
Register all formula directories in the search path before applying composes
Run a preflight load of every `with:` reference in CI

When it happens

Trigger: ApplyExpansions processes compose.Map rules and parser.LoadByName(rule.With) fails — formula not found in search paths, file unreadable, or parse error.

Common situations: Typo in the `with:` formula name; formula file missing from the search path; formula directory not registered; syntax error inside the formula file.

Related errors

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