ErrLookup › Background articles › "no subcommand specified" and "... is required": CLI errors when a required argument is missing

"no subcommand specified" and "... is required": CLI errors when a required argument is missing

"No subcommand specified", "No arguments provided", "Specify a ...", "--id is required" - these errors fire when a command-line tool is invoked without an argument it treats as mandatory: a dispatcher given no subcommand (rtk go, hadoop aws s3guard, php artisan october:util) or a management command missing a required flag, positional, or argument pair (Phabricator bin/ workflows, pnpm access, gem, siyuan). This page covers the family across 13 libraries and 89 documented records: why the tools refuse to guess, how the errors surface, which script-level mistakes trigger them, and how to fix and prevent them.

Distilled from 89 documented records across 13 repositories.

Background

These errors come from the argument-parsing layer that runs before a tool does any real work, and the family has two dominant shapes. The first is the subcommand dispatcher: rtk's go, gt, sbt, and dotnet proxies, October CMS's october:util, and Hadoop's "hadoop aws s3guard" each route an invocation to a filtered handler or a proxied child process; with an empty argv there is no token to route, so they refuse up front rather than spawn a bare process (rtk's sbt guard, for example, keeps you out of sbt's interactive shell). The second is the required-argument check: Phabricator's bin/ management workflows, pnpm access, Ruby's gem command, SiYuan's asset CLI, and others validate flags and positionals before touching state, and abort as soon as a mandatory slot is empty.

The family exists because these tools refuse to guess, and the records show the cost of guessing would be real. Phortune's invoice workflow will not invent a billing range because an incorrect one can double-bill customers. bin/auth unlimit demands --all so its semantics stay stable when narrower resets are added. rtk's dispatchers need a verb before their output filters can attach. So the check fires before any side effect: pnpm's access commands fail at argument parsing with nothing sent to the registry, Phabricator's usage guards throw before any database access, and rtk bails before spawning a process.

From the caller's side the result is almost always a usage message plus a non-zero exit, but the exact surface is library-specific. Phabricator signals caller misuse with PhutilArgumentUsageException, which prints usage text to stderr instead of a stack trace. Hadoop's S3GuardTool prints help and throws ExitUtil.ExitException with exit code 42 (EXIT_USAGE). October's october:util mimics Symfony's "no commands defined in the namespace" wording and appends the available utility names. Several messages double as discovery: the herald test error lists the content types valid for your object, the garbage-collector error lists valid collector constants, and october:util prints a "Did you mean one of these?" list. One outlier, Diviner's "Specify one or more files to atomize", is a plain Exception and surfaces with a stack trace rather than a usage message.

What counts as missing also varies across the family, and that is where the subtler triggers live. Arguments can be present yet resolve to nothing: Phabricator's pull, discover, and clusterize workflows resolve callsigns through a locality check, so a correctly spelled name on a host with no bound working copies still yields zero repositories, and a shell glob that matches nothing leaves diviner atomize with no files. Pairs must arrive complete: gitbutler's "but agentlog skim [TARGET] [VALUE]" rejects either half alone because the default applies only when both are omitted, and phortune's --last/--next must define both bounds of the billing range. Ruby's gem command treats every leading dash entry as a flag, so an invocation made entirely of options still has an empty name list. The required set itself drifts with versions: S3Guard's old subcommands were removed with the DynamoDB metadata store, and Phabricator workflow flags change between releases, so a command that once worked can start landing in this family.

Common causes

What usually fixes it

Documented occurrences

…and 69 more across the corpus — use search.

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