golang/go · error

condition %q cannot be used with a suffix

Error message

condition %q cannot be used with a suffix

What it means

Thrown by Engine.conditionsActive when a condition registered as a non-prefix Cond (Condition, BoolCondition, OnceCondition) is used with a ':suffix' in a bracket. These condition types have Prefix==false and explicitly reject suffixes (they return ErrUsage for non-empty suffix). The check at engine.go:523-525 fires before Eval.

Source

Thrown at src/cmd/internal/script/engine.go:524

			b.WriteString("'")
		} else {
			b.WriteString(arg)
		}
	}
	return b.String()
}

func (e *Engine) conditionsActive(s *State, conds []condition) (bool, error) {
	for _, cond := range conds {
		var impl Cond
		prefix, suffix, ok := strings.Cut(cond.tag, ":")
		if ok {
			impl = e.Conds[prefix]
			if impl == nil {
				return false, fmt.Errorf("unknown condition prefix %q; known: %v", prefix, slices.Collect(maps.Keys(e.Conds)))
			}
			if !impl.Usage().Prefix {
				return false, fmt.Errorf("condition %q cannot be used with a suffix", prefix)
			}
		} else {
			impl = e.Conds[cond.tag]
			if impl == nil {
				return false, fmt.Errorf("unknown condition %q", cond.tag)
			}
			if impl.Usage().Prefix {
				return false, fmt.Errorf("condition %q requires a suffix", cond.tag)
			}
		}
		active, err := impl.Eval(s, suffix)

		if err != nil {
			return false, fmt.Errorf("evaluating condition %q: %w", cond.tag, err)
		}
		if active != cond.want {
			return false, nil
		}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Remove the suffix from the bracket — use [cgo] not [cgo:enabled].
2. Consult the condition's summary via 'help' to confirm whether it is a prefix condition.
3. If you need a parameterized variant, register a custom PrefixCondition with a distinct name.

Example fix

// before
[cgo:enabled] exec go build
// after
[cgo] exec go build

// Verify a condition accepts a suffix before writing [prefix:value].
func acceptsSuffix(conds map[string]script.Cond, prefix string) bool {
    c, ok := conds[prefix]
    return ok && c.Usage().Prefix
}

When it happens

Trigger: Writing [root:foo], [cgo:enabled], [symlink:yes] — root/cgo/symlink are bool or simple conditions that take no suffix.

Common situations: Assuming every condition takes a suffix; confusing a prefix condition (GOOS, GOARCH, GODEBUG) with a boolean one (root, cgo, go-builder); typo appending ':value' to a bool condition.

Related errors

• unrecognized GOOS %q
• unrecognized GOARCH %q
• unrecognized compiler %q
• unknown condition prefix %q; known: %v
• unknown condition %q

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/d2ff8dd80d63f770. Report an issue: GitHub.