ErrLookup › Background articles › "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools

"unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools

"unknown output mode", "invalid value for flag", "expects true/false", and similar messages are invalid flag value errors: a CLI accepted your flag but rejected the value because it isn't in the command's whitelist of allowed values (like -o json on a command that only supports -o wide or -o name) or can't be parsed as the flag's type (like yes for a boolean flag). Developers hit these most often when copying flag values between subcommands of the same tool, scripting with unvalidated env variables, or guessing at enum spellings and casing. The fix is almost always to check --help and use an exact, case-sensitive value from the command's accepted set.

Distilled from 98 documented records across 24 repositories.

Background

This family covers errors produced entirely client-side, at flag-parsing or pre-run validation time. Nothing has been executed against a server, cluster, or file system yet — the command compared your value against an allowlist (or a type parser) and stopped before doing real work. That's why tools like argo, cilium/hubble, pulumi, vitess, and golangci-lint can return these errors in milliseconds, and why the fix never involves restarting a daemon or checking connectivity.

The mechanism varies by implementation, and the variation matters for debugging. Some libraries validate at parse time via typed flag values: urfave/cli's BoolFlag Set rejects anything strconv.ParseBool can't read, and its generic wrapper "invalid value %q for flag -%s: %v" nests the underlying parse cause in the trailing %v. Cobra/pflag-based tools (cilium, hubble, pulumi, golangci-lint) run Set hooks during parsing, so a bad --identity or --ip-trace-id aborts parsing with a wrapped error. Others validate later, in the command body: argo's "unknown output mode: %s" only fires as a defensive fallback because the EnumFlagValue should have caught bad values earlier — meaning if you see it, the flag was likely set programmatically or bypassed validation. And some tools are deliberately non-fatal: agentmemory warns "Unknown --tools value" and falls back to 'all', while vitess's vtgate exits rather than starting with a buffer window under 1s.

The most reliable signal in these errors is that most of them enumerate the accepted values. jaeger's mapping error lists all four mapping types; crush names 'catwalk' or 'hyper'; pulumi's --approval-mode names manual, balanced, auto; hubble's --identity error lists reserved identity names. When the message lists options, the answer is literally in the error — you only need to match spelling and casing exactly, because matching is almost always case-sensitive (beads rejects --dolt-auto-commit=OFF, pulumi rejects --approval-mode Manual).

Across the 24 repositories, three recurring value shapes dominate: output-format enums (--output/-o, where each argo, cilium, and pulumi subcommand has its own different allowlist), boolean-like flags (which variously accept true/false only, strconv.ParseBool's set, or true/false/1/0), and numeric or path-typed values (uint64 trace ids, single-character delimiters, absolute paths, RSA key sizes capped at 4096). The exact accepted set for a flag is library- and even subcommand-specific, so a value valid for one command in a tool is frequently invalid for its sibling commands.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 78 more across the corpus — use search.

Honest provenance: generated on 2026-09-03 from AI-assisted analysis of the linked records. See how records are made.