jackwener/OpenCLI · error · ArgumentError

Argument "${argDef.name}" is required.

Error message

Argument "${argDef.name}" is required.

What it means

coerceAndValidateArgs enforces each command's declared argument definitions before execution. When an argument marked required is missing, empty string, null, or undefined, it throws ArgumentError with the argument's name and its help text. This fails fast so commands never run with missing mandatory inputs.

Source

Thrown at src/execution.ts:61

const _moduleMtimes = new Map<string, number>();
const _userClisDir = `${os.homedir()}/.opencli/clis/`;

type TraceMode = 'off' | 'on' | 'retain-on-failure';

function normalizeTraceMode(raw: unknown): TraceMode {
  if (raw === undefined || raw === null || raw === '' || raw === 'off') return 'off';
  if (raw === 'on' || raw === 'retain-on-failure') return raw;
  throw new ArgumentError(`--trace must be one of: off, on, retain-on-failure. Received: "${String(raw)}"`);
}

export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {
  const result: CommandArgs = { ...kwargs };

  for (const argDef of cmdArgs) {
    const val = result[argDef.name];

    if (argDef.required && (val === undefined || val === null || val === '')) {
      throw new ArgumentError(
        `Argument "${argDef.name}" is required.`,
        argDef.help ?? `Provide a value for --${argDef.name}`,
      );
    }

    if (val !== undefined && val !== null) {
      if (argDef.type === 'int' || argDef.type === 'number') {
        const num = Number(val);
        if (!Number.isFinite(num)) {
          throw new ArgumentError(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
        }
        if (argDef.type === 'int' && !Number.isInteger(num)) {
          throw new ArgumentError(`Argument "${argDef.name}" must be a valid integer. Received: "${val}"`);
        }
        result[argDef.name] = num;
      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {
        if (typeof val === 'string') {
          const lower = val.toLowerCase();

View on GitHub (pinned to 49907e53dc)

Solutions

1. Supply the required argument, e.g. --site acme (see the help text in the error message).
2. Guard shell/script variables so empty values are omitted rather than passed as ''."
3. In programmatic use, check required kwargs before invoking the command.
4. Verify the argument name spelling matches the command's arg definition.

Example fix

// before
await run('whoami', {})
// after
await run('whoami', { site: 'acme' })

function requireArgs(kwargs: Record<string, unknown>, required: string[]) {
  const missing = required.filter(k => kwargs[k] === undefined || kwargs[k] === null || kwargs[k] === '');
  if (missing.length) throw new Error(`Missing required argument(s): ${missing.map(m => `--${m}`).join(', ')}`);
}
requireArgs(kwargs, ['site']);

function hasValue<T>(v: T | undefined | null | ''): v is T {
  return v !== undefined && v !== null && v !== '';
}

try {
  await opencli.run(cmd, kwargs);
} catch (e) {
  if (/Argument ".+" is required\./.test(e.message)) {
    console.error(`${e.message} ${e.help ?? ''}`);
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling a command without supplying a required --flag (e.g. a site or url argument), or explicitly passing --flag "" / --flag=null via kwargs.

Common situations: Forgetting a mandatory option after a CLI refactor; shell variables expanding to empty strings; programmatically building kwargs where a key is present but null/empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ${label} is required
• ${label} must be a positive integer
• ${label} must be <= ${maxValue}
• ${label} must be a numeric ID
• ${label} cannot be empty

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/2bfd2fd93fd427ab. Report an issue: GitHub.