gastownhall/beads · error

applying inline expansions: %w

Error message

applying inline expansions: %w

What it means

cmd/bd/cook.go:188 wraps errors from formula.ApplyInlineExpansions(resolved.Steps, parser), which expands steps marked for inline inclusion into their full sub-steps (embedding another formula's steps in place). It fails when an inline reference cannot be resolved: the referenced formula/step doesn't exist, can't be parsed, or the expansion recurses too deeply (self-inclusion).

Source

Thrown at cmd/bd/cook.go:188

		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 {
		resolved.Steps = formula.ApplyAdvice(resolved.Steps, resolved.Advice)
	}

	// Apply inline step expansions
	inlineExpandedSteps, err := formula.ApplyInlineExpansions(resolved.Steps, parser)
	if err != nil {
		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)

View on GitHub (pinned to 71377f2769)

Solutions

1. Confirm the inline-referenced formula exists in .beads/formulas/ (or is a valid path) and parses on its own.
2. Check for self- or mutual-inclusion (A inlines B, B inlines A) and break the recursion.
3. Sync the repository so all inlined formulas are present locally.
4. Update stale inline references after any formula rename.

Example fix

// before (step frontmatter)
inline: shared-setup   # file never committed
// after
inline: .beads/formulas/shared-setup.md   # or commit shared-setup to the registry

func inlineRefsLoadable(steps []*formula.Step, load func(string) (*formula.Formula, error)) error {
	for _, s := range steps {
		for _, ref := range s.InlineRefs() {
			if _, err := load(ref); err != nil {
				return fmt.Errorf("inline ref %q unloadable: %w", ref, err)
			}
		}
	}
	return nil
}

func inlineRefResolvable(ref string, registry map[string]*formula.Formula) bool {
	_, ok := registry[ref]
	return ok
}

steps, err := formula.ApplyInlineExpansions(resolved.Steps, parser)
if err != nil {
	return fmt.Errorf("check inline references (missing file or self-inclusion): %w", err)
}

When it happens

Trigger: A step carries inline-expansion syntax pointing at a formula name or step id that parser cannot load (missing file/registry entry), references itself directly or transitively, or the referenced content fails to parse during expansion.

Common situations: Inlining a shared formula that lives only in another repo; renaming an inlined formula without updating call sites; accidentally inlining a formula that (transitively) inlines itself; a partially committed formula set where the inlined file is missing locally.

Related errors

• inline expansion depth limit exceeded: max %d levels
• applying inline expansions to %q: %w
• branch: from step %q not found
• branch: join step %q not found
• expand %q: %w

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