gastownhall/beads · error

expand %q: %w

Error message

expand %q: %w

What it means

Wraps an error returned by expandStep while expanding the target step of an `expand` rule. The inner error is most often the depth-limit error or a variable/template substitution failure; this wrapper adds the target step ID for context.

Source

Thrown at internal/formula/expand.go:81

		if err != nil {
			return nil, fmt.Errorf("expand: loading %q: %w", rule.With, err)
		}

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

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

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

		// Expand the target step (start at depth 0)
		expandedSteps, err := expandStep(targetStep, expFormula.Template, 0, vars)
		if err != nil {
			return nil, fmt.Errorf("expand %q: %w", rule.Target, err)
		}

		// Propagate target step's dependencies to root steps of the expansion.
		// Root steps are those whose needs/dependsOn only reference IDs within
		// the expansion (or are empty) — they are the entry points.
		propagateTargetDeps(targetStep, expandedSteps)

		// Replace the target step with expanded steps
		result = replaceStep(result, rule.Target, expandedSteps)
		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)
		}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped inner error for the root cause
2. Reduce recursion in the expansion template or refactor into explicit steps
3. Verify all {var} placeholders in the template are provided via formula defaults or rule.Vars

expanded, err := formula.ApplyExpansions(steps, compose)
if err != nil {
    var de *formula.DepthError // or match "expand %q:"
    if strings.Contains(err.Error(), "depth limit") {
        return fmt.Errorf("expansion too deep for target %s: %w", rule.Target, err)
    }
    return err
}

When it happens

Trigger: ApplyExpansions -> expandStep fails while processing a compose `expand` rule targeting step `rule.Target` (e.g. expansion depth exceeded DefaultMaxExpansionDepth=5, or template placeholder issues).

Common situations: Deeply recursive expansion templates; template referencing undefined variables causing substitution errors; chained expansions expanding each other beyond the depth limit.

Related errors

• applying inline expansions: %w
• applying expansions: %w
• applying expansions to %q: %w
• standalone expansion %q: %w
• expand: target step %q not found

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