invalid step condition format: %q (expected {{var}} or {{var

Error message

invalid step condition format: %q (expected {{var}} or {{var}} == value)

What it means

EvaluateStepCondition evaluates a Step.Condition string against supplied variables. Supported forms are `{{var}}` (truthiness) and comparisons like `{{var}} == value` / `!=`. Any condition string not matching these formats falls through to this error, unlike unmatched comparisons which return a bool.

Source

Thrown at internal/formula/stepcondition.go:81

	if m := stepCondComparePattern.FindStringSubmatch(condition); m != nil {
		varName := m[1]
		operator := m[2]
		expected := strings.TrimSpace(m[3])

		// Remove quotes from expected value if present
		expected = unquoteValue(expected)

		actual := vars[varName]

		switch operator {
		case "==":
			return actual == expected, nil
		case "!=":
			return actual != expected, nil
		}
	}

	return false, fmt.Errorf("invalid step condition format: %q (expected {{var}} or {{var}} == value)", condition)
}

// isTruthy returns true if a value is considered "truthy" for step conditions.
// Falsy values: empty string, "false", "0", "no", "off"
// All other values are truthy.
func isTruthy(value string) bool {
	if value == "" {
		return false
	}
	lower := strings.ToLower(value)
	switch lower {
	case "false", "0", "no", "off":
		return false
	}
	return true
}

// unquoteValue removes surrounding quotes from a value if present.

View on GitHub (pinned to 71377f2769)

Solutions

Rewrite the condition to the supported form: `{{var}}`, `{{var}} == value`, or `{{var}} != value`.
Check exact syntax: double curly braces, no missing closing brace, operator surrounded by spaces.
Replace complex boolean conditions with multiple steps or pre-computed variables.
Inspect the failing step's `condition` field in the formula file and correct it.

Example fix

// before
condition: "{{count}} >= 3"
// after
condition: "{{count}} == 3"

Defensive patterns

Strategy: validation

Validate before calling

func validCondition(c string) bool {
    c = strings.TrimSpace(c)
    if strings.HasPrefix(c, "{{") && strings.HasSuffix(c, "}}") && !strings.Contains(c[2:len(c)-2], "}}") {
        inner := strings.TrimSpace(c[2 : len(c)-2])
        if !strings.Contains(inner, " ") { return true }
        parts := strings.SplitN(inner, " ", 2)
        if len(parts) == 2 && strings.Count(parts[1], " ") == 1 {
            op := strings.Fields(parts[1])[0]
            return op == "==" || op == "!="
        }
    }
    return false
}

Try / catch

if err := run(); err != nil && strings.Contains(err.Error(), "invalid step condition format") { /* surface condition string to the user for fixing */ }

Prevention

Restrict formula conditions to {{var}}, {{var}} == value, {{var}} != value.
Lint step conditions when parsing formula files, before execution.
Document that boolean operators (&&, ||, >=) are unsupported.

When it happens

Trigger: FilterStepsByCondition (directly or transitively) encounters a step whose Condition is neither `{{var}}` nor `{{var}} == value` / `{{var}} != value`: wrong braces, missing operand, unsupported operator (e.g. `>`), or malformed spacing.

Common situations: Formula authors write conditions using arbitrary expressions (`{{a}} && {{b}}`, `{{count}} >= 3`) assuming full expression support, or typo the template delimiters.

Related errors

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