ErrLookup › Background articles › "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it

"--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it

"--flag is required", "must specify either create or append", and "requires --execute" errors are a family of fail-fast argument validation failures thrown by CLIs and builder APIs when a mandatory flag or mode was omitted, left empty, or silently dropped from the command line. Developers hit them in scripts and CI when shell variables are unset, when wrappers mangle argv, or when a safety-gated write command runs without its explicit opt-in flag. Fixing them means supplying the flag — and hardening the scripts that let it disappear.

Distilled from 103 documented records across 20 repositories.

Background

This family is produced at the outermost boundary of a tool: argument parsing and pre-flight validation, before any real work happens. The checks are deliberately the first thing a command's RunE (cobra-style Go CLIs), argument validator (Node CLIs), or build() dispatcher (builder-style APIs like Hadoop's HdfsDataOutputStreamBuilder) runs. A missing flag aborts the operation before any filesystem write, cloud request, or remote API call is made. Several records state this explicitly: SiYuan's guards fire before model calls and even before --dry-run branches, cilium clustermesh disconnect validates --destination-context before any cluster API call, and Hadoop refuses build() when the CreateFlag set contains no mode. The practical effect is that these errors are pure usage errors — nothing changed, nothing was fetched, and retrying with the right command line is always safe. Why does the family exist at all, instead of defaults? Three reasons recur across the records. First, there is genuinely no sensible default: SiYuan's inbox convert has nowhere to write without a target notebook, and a binary .docx export cannot be streamed to stdout, so --output must be named. Second, the value is destructive or sensitive, so the tool demands explicit opt-in: OpenCLI's requireExecute gates remote writes and Pixiv downloads behind --execute, zeroclaw refuses to hang on an invisible interactive prompt when stdin is not a TTY without --description, oh-my-pi requires --from-local before uploading local credentials, and Phabricator refuses to guess which path prefix to move from. Third, ambiguity is dangerous: Hadoop's builder must be told whether you are creating or appending, and CodeWhale's serve command accepts exactly one transport, failing both when none and when two are selected. From the caller's side the message usually arrives instantly and names the missing flag, though the exact wording varies: plain statements ("--id is required", "--parent is required"), multi-option lists (pulumi's "pass --role, --fga-role-id, or --fga-role-name"), mode-invariant rules (CodeWhale's "choose exactly one server mode"), and inner-API wrapping (cilium's dpgen surfaces "writing header: writing package header: package name cannot be empty"). Ordering matters and is library-specific: SiYuan documents the precedence of each check (notebook before ids in inbox convert, id before output in docx export), so the error you see reflects whichever guard ran first, not the only thing wrong. Some validators also distinguish absent from empty — pulumi org member edit tracks cobra's flag .Changed, so an explicitly empty --role "" counts as a change while an absent flag does not — whereas SiYuan rejects both omission and empty string identically. Across libraries, the family divides into two shapes. Mandatory-value errors ("--id is required", "--notebook is required") ask for a piece of data the command cannot proceed without. Mandatory-consent errors ("requires --execute", "requires an explicit source", "pass --all") ask for a deliberate choice, often to protect you from an accidental destructive or far-reaching action. Bundler's update_requires_all_flag is notable in that the consent gate is itself opt-in configuration: a bare bundle update is rejected only when the setting is enabled, which is common in CI. The underlying triggers, however, are shared: flags omitted by hand, empty shell variables silently deleting tokens from argv, typos that parse to nothing (SiYuan notes unknown flag names like --files land as an absent --file), positional arguments that parsers ignore, and scripts that join empty arrays into a flag value.

Common causes

What usually fixes it

Documented occurrences

…and 83 more across the corpus — use search.

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