golang/go · error

unknown condition prefix %q; known: %v

Error message

unknown condition prefix %q; known: %v

What it means

Thrown by Engine.conditionsActive when a condition bracket contains a colon (e.g. [prefix:suffix]) but the prefix is not a key in e.Conds. The message appends the full list of registered condition names to help diagnose the typo or missing registration. This is distinct from ListConds' variant which omits the 'known:' list.

Source

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

			// Quote the argument to a form that would be parsed as a single argument.
			b.WriteString("'")
			b.WriteString(strings.ReplaceAll(arg, "'", "''"))
			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)
		}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Read the 'known: [...]' list in the error and pick the correct prefix name.
2. If the condition is toolchain-specific (cgo, race, GOEXPERIMENT, buildmode, etc.), ensure scripttest.AddToolChainScriptConditions was called when building the engine.
3. Register the custom condition with e.Conds[name] before running the script.

Example fix

// before — engine built without toolchain conditions
[GOEXPERIMENT:fieldtrack] exec go build
// after
scripttest.AddToolChainScriptConditions(t, e.Conds, runtime.GOOS, runtime.GOARCH)
[GOEXPERIMENT:fieldtrack] exec go build

import "maps"

func condPrefixKnown(conds map[string]script.Cond, prefix string) bool {
    _, ok := conds[prefix]
    return ok
}

// Before running a script with generated condition tags:
for _, tag := range tags {
    if prefix, _, ok := strings.Cut(tag, ":"); ok && !condPrefixKnown(e.Conds, prefix) {
        return fmt.Errorf("unregistered condition prefix %q; known: %v", prefix, maps.Keys(e.Conds))
    }
}

When it happens

Trigger: Using [UNKNOWN:suffix] where UNKNOWN was never registered; referencing a toolchain-only condition (buildmode, GOEXPERIMENT, race) without having called scripttest.AddToolChainScriptConditions; typo like [GOOSX:linux].

Common situations: Forgetting to add toolchain conditions to the engine's Conds map; using a condition introduced in a newer Go version on an older runtime; copy-paste typo in the prefix.

Related errors

• unrecognized GOOS %q
• unrecognized GOARCH %q
• unrecognized compiler %q
• condition %q cannot be used with a suffix
• unknown condition %q

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