ErrLookup › Background articles › "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them

"missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them

"missing required argument", "the following required arguments were not provided", and "<argument> is required" are the messages libraries emit when a call or command arrives without a value the library cannot proceed without: a selector role in k6 browser tests, a database name in SpacetimeDB CLI commands, a model name in litellm, a rule slot in a tree-sitter grammar. This article covers the whole family (106 documented records across 20 repositories): which validation layers produce these errors, why strictness differs between libraries, and the fixes that hold everywhere.

Distilled from 106 documented records across 20 repositories.

Background

These errors come from validation at the boundary between caller and library, and they fire before any real work starts. The layer varies by library. CLI argument parsers such as clap print a usage block naming the missing positional (SpacetimeDB's <database>, mise's --url). JavaScript API bridges run nullish guards before building selectors or requests: k6's browser module checks the first argument of every getByRole, getByPlaceholder, getByAltText, and getByTestId call with an IsNullish test, because no CDP query can be constructed without it. Internal kwarg validators guard plumbing parameters (litellm's completion-to-responses bridge requires 'model' as a string and 'optional_params' as a dict). Planner and resolver functions require a seed to expand from (ECC's install planners refuse to run with no profile, module, or component selection). Kernel plugin APIs check argument count or type up front (siyuan's client.fetch, storage.put, and storage.watcher.add).

The checks exist to fail fast: each call site has downstream work that is impossible without the value. There is no ARIA selector without a role, no dependency plan without a selection, no tool stub without an artifact URL, no hardened git command without a subcommand position to splice flags into. litellm's bridge deliberately stops a modelless request before it reaches a provider; mise's generator refuses to emit an empty stub.

From the caller's side, the trigger is usually one of two things: the argument was omitted outright, or a variable that was supposed to carry it evaluated to undefined (an unset env var, a data-fixture row missing the field, an absent config key, a lookup that returned nothing). The message vocabulary differs by library: k6 names the argument ("missing required argument 'role'"), clap prints the missing positional plus a usage line, ECC describes which selections would have counted, and some messages are actively misleading. yazi reports "Unknown copy type" or even a message about Cargo build limitations when an action's argument map lookup fails, and tree-sitter's "Undefined symbol" means a rule slot was literally undefined, which is distinct from the ReferenceError the $ proxy throws for a misspelled rule name.

How strict the check is turns out to be library-specific. k6's guards reject only null and undefined; an empty string passes and silently builds a locator that matches nothing. siyuan's storage.put is count-only: once two arguments exist, non-string values are coerced with String() rather than rejected, so only a genuinely missing argument errors. ECC normalizes ids and rejects whitespace-only values, and its locale option counts as a selection because it is injected as an included component. Some sites require a type (siyuan's client.fetch path must be a JS string), others mere presence. polars uses a NO_DEFAULT sentinel to distinguish "not given" from "passed as None", which is why its case surfaces as a TypeError about a keyword-only argument. yazi adds a consumption dimension: take() removes the entry from the action's args map, so a second consumer reading the same name or index fails exactly like a missing argument.

Common causes

• Argument omitted entirely. The call is made with nothing in the required slot: getByRole() with zero arguments, `spacetime call --no-config` with nothing supplied, resolveInstallPlan({}), or field('name') without a rule in tree-sitter. The guard fires before any work starts.
• Variable resolved to undefined or null. The slot is filled by a variable that evaluated to nullish: an unset __ENV entry in k6, a data-fixture row missing the field (row.placeholder), an absent config key, or a lookup like list[0]?.id on an empty list. Passing an explicit null or undefined triggers the same guard.
• Name or casing mismatch across the boundary. The sender attached the value under a different key than the receiver reads. yazi's DataKey lookup is exact-match including case; ECC silently drops selections on option-key casing typos such as moduleIds vs module_ids; k6 fixtures fail on obj['data-test'] vs obj.testId.
• Positional shift or wrong slot. An omitted earlier positional shifts the indices a receiver reads (yazi take(0)/take(1)), or the wrong value occupies the first slot: passing an options object to page.waitForURL() or siyuan's fetch({path: ...}) instead of the string the library expects. impeccable's `hooks ignore-value Inter` puts the value where the rule id belongs.
• Keyword-only parameter not passed by keyword. In polars, replace_with is keyword-only: passing the replacement positionally raises this error instead of binding, and parallel pattern/replacement lists need the explicit replace_with= keyword.
• A wrapper or shell layer dropped the value. Quoting in a shell or CI layer can drop the values of --profile/--modules; empty shell variables become absent arguments; custom code forwarding only a subset of kwargs (litellm's bridge handler) omits keys the normal pipeline always supplies; spreading an options object that lacks the field (AFFiNE's set(key, opts.blob)) forwards undefined.
• The implicit default the caller relied on is gone. SpacetimeDB with --no-config, or run outside a directory containing spacetime.json, cannot imply the database, so both positionals must be supplied; ECC planning without a target that has a default profile has no seed selection; in mise, only --lock and --fetch legitimately run without a URL.
• A flag was given that does not count as the required value. Exclude-only or bare flags never satisfy a selection requirement. ECC's --without sets exclusions but not a base selection, and bare flags like --dry-run or --json count for nothing; when impeccable's flags consume all tokens, the positionals the command needs are empty.

What usually fixes it

• Pass the required argument explicitly, in the form the library documents: a string or RegExp for k6's getBy* methods, both positionals when config discovery is off (`spacetime call <database> <function_name> <args...> --no-config`), and the dict form in polars ({pattern: replacement}), which cannot hit the error.
• Default dynamic values at the call site instead of passing possibly-undefined variables: const role = cfg.role ?? 'button' before the call, and skip the step when the value is legitimately absent (if (alt) loc = page.getByAltText(alt)).
• Validate inputs at the boundary, before the library sees them: check fixtures, env vars, and config keys during setup so missing fields fail with your own message; filter blank entries when splitting CLI input (.map(s => s.trim()).filter(Boolean)); assert route constants and path variables exist before composing calls.
• Guard wrapper scripts and CLIs before invoking the library: check $# before building the command, only pass --profile "$P" when P is non-empty, and enforce 'at least one selection' as a usage error before calling planners so users get your message, not the library's.
• Keep names identical on both sides of the boundary: emitter argument names must match receiver keys exactly, including case; prefer named arguments over positional ones to avoid index shifts; centralize selectors, roles, test IDs, and kernel routes in single constants modules so a missing key fails visibly.
• Let the toolchain catch omissions while you write: use the library's TypeScript typings (k6 browser typings flag zero-argument calls in the editor), lint for typo'd variables that silently become undefined, and add a smoke test per custom command that dispatches with all required arguments attached.

Documented occurrences

• the following required arguments were not provided: <{}> Usage: {} (clockworklabs/SpacetimeDB)
• missing required argument 'placeholder' (grafana/k6)
• No install profile, module IDs, included components, or legacy languages were provided (affaan-m/ECC)
• Unknown copy type: {} (sxyazi/yazi)
• classifier-approved Git read was missing its literal subcommand (Hmbown/CodeWhale)
• `replace_with` argument is required if `patterns` argument is not a Mapping type (pola-rs/polars)
• Undefined symbol (tree-sitter/tree-sitter)
• No install profile, module IDs, or included component IDs were provided (affaan-m/ECC)
• No legacy languages were provided (affaan-m/ECC)
• path required (siyuan-note/siyuan)
• model is required (BerriAI/litellm)
• ErrorCode.TransformerError: value is required (toeverything/AFFiNE)
• missing required argument 'role' (grafana/k6)
• Due to Cargo's limitations, Yazi on crates.io must be built with `cargo install --force yazi-build` (sxyazi/yazi)
• Pass a rule id and value, e.g. ${IMPECCABLE_COMMAND} hooks ignore-value overused-font Inter (pbakaus/impeccable)
• missing required argument 'altText' (grafana/k6)
• Either --url or --platform-url must be specified (jdx/mise)
• path and content required (siyuan-note/siyuan)
• missing required argument 'testId' (grafana/k6)
• missing required argument 'url' (grafana/k6)

…and 86 more across the corpus — use search.

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