What causes "filtering steps by condition: %w" in gastownhall/beads?

Inspect the wrapped cause to find the offending condition expression and step

filtering steps by condition: %w

Error message

filtering steps by condition: %w

What it means

Thrown when formula.FilterStepsByCondition fails while evaluating step `when:` conditions during cooking. Steps can carry conditions evaluated against merged variables; a malformed condition expression (unparseable/unevaluable) makes filtering fail and aborts the cook with the formula already partially resolved.

Source

Thrown at cmd/bd/cook.go:793

	}

	// Apply step condition filtering if vars provided (bd-7zka.1)
	// This filters out steps whose conditions evaluate to false
	if conditionVars != nil {
		// Merge with formula defaults for complete evaluation
		mergedVars := make(map[string]string)
		for name, def := range resolved.Vars {
			if def != nil && def.Default != nil {
				mergedVars[name] = *def.Default
			}
		}
		for k, v := range conditionVars {
			mergedVars[k] = v
		}

		filteredSteps, err := formula.FilterStepsByCondition(resolved.Steps, mergedVars)
		if err != nil {
			return nil, fmt.Errorf("filtering steps by condition: %w", err)
		}
		resolved.Steps = filteredSteps
	}

	// Handle standalone expansion formulas (bd-qzb).
	// Expansion formulas store content in Template, not Steps. Materialize
	// the template into Steps using a synthetic "main" target so the normal
	// cooking pipeline can process them.
	if resolved.Type == formula.TypeExpansion && len(resolved.Template) > 0 {
		expansionVars := make(map[string]string)
		for name, def := range resolved.Vars {
			if def != nil && def.Default != nil {
				expansionVars[name] = *def.Default
			}
		}
		if conditionVars != nil {
			for k, v := range conditionVars {
				expansionVars[k] = v

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped cause to find the offending condition expression and step
Fix the `when:` expression syntax on that step (valid operators, balanced parens)
Ensure every variable the condition references is defined in vars or conditionVars and evaluates to a clean string
Test the condition in isolation via the formula test/verify path
Quote or escape variable values that may contain characters the condition parser treats specially

Example fix

# before
steps:
  - id: deploy
    when: "env == &&"   # malformed expression
    template: deploy
# after
steps:
  - id: deploy
    when: "env == 'prod'"
    template: deploy

Defensive patterns

Strategy: validation

Validate before calling

// Sanity-check step conditions against provided vars before cooking
for _, s := range f.Steps {
    if s.When != "" {
        if err := formula.CheckConditionSyntax(s.When); err != nil {
            return fmt.Errorf("step %q: bad condition %q: %w", s.ID, s.When, err)
        }
    }
}
// and ensure all referenced vars are present
for k := range referencedVars(f) {
    if _, ok := mergedVars[k]; !ok { return fmt.Errorf("condition var %q missing", k) }
}

Try / catch

if err := runCook(); err != nil && strings.Contains(err.Error(), "filtering steps by condition") {
    // inner error names the malformed expression; fix the step's `when:`
    log.Printf("condition filter failed: %v", errors.Unwrap(err))
}

Prevention

Write conditions with simple `var == 'value'` forms; avoid exotic operators
Quote variable values that may contain spaces or special characters
Provide defaults for condition variables in the formula vars section
Test condition-heavy formulas via bd verify before production use

When it happens

Trigger: A formula defines steps with condition expressions and the cook path (bd cook, bd pour, verifyFormula) evaluates them against mergedVars; filtering errors when a condition's syntax is invalid or its expression cannot be evaluated against the provided variable map.

Common situations: Hand-written `when:` expression with unbalanced parentheses or an unsupported operator; condition references a variable with a value type the evaluator rejects; variable interpolated to an empty/unparseable string before evaluation.

Related errors

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