{"record":{"id":"2bfd2fd93fd427ab","repo":"jackwener/OpenCLI","slug":"argument-argdef-name-is-required","errorCode":null,"errorMessage":"Argument \"${argDef.name}\" is required.","messagePattern":"Argument \"(.+?)\" is required\\.","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":61,"sourceCode":"const _moduleMtimes = new Map<string, number>();\nconst _userClisDir = `${os.homedir()}/.opencli/clis/`;\n\ntype TraceMode = 'off' | 'on' | 'retain-on-failure';\n\nfunction normalizeTraceMode(raw: unknown): TraceMode {\n  if (raw === undefined || raw === null || raw === '' || raw === 'off') return 'off';\n  if (raw === 'on' || raw === 'retain-on-failure') return raw;\n  throw new ArgumentError(`--trace must be one of: off, on, retain-on-failure. Received: \"${String(raw)}\"`);\n}\n\nexport function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {\n  const result: CommandArgs = { ...kwargs };\n\n  for (const argDef of cmdArgs) {\n    const val = result[argDef.name];\n\n    if (argDef.required && (val === undefined || val === null || val === '')) {\n      throw new ArgumentError(\n        `Argument \"${argDef.name}\" is required.`,\n        argDef.help ?? `Provide a value for --${argDef.name}`,\n      );\n    }\n\n    if (val !== undefined && val !== null) {\n      if (argDef.type === 'int' || argDef.type === 'number') {\n        const num = Number(val);\n        if (!Number.isFinite(num)) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be a valid number. Received: \"${val}\"`);\n        }\n        if (argDef.type === 'int' && !Number.isInteger(num)) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be a valid integer. Received: \"${val}\"`);\n        }\n        result[argDef.name] = num;\n      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {\n        if (typeof val === 'string') {\n          const lower = val.toLowerCase();","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L43-L79","documentation":"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.","triggerScenarios":"Calling a command without supplying a required --flag (e.g. a site or url argument), or explicitly passing --flag \"\" / --flag=null via kwargs.","commonSituations":"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.","solutions":["Supply the required argument, e.g. --site acme (see the help text in the error message).","Guard shell/script variables so empty values are omitted rather than passed as ''.\" ","In programmatic use, check required kwargs before invoking the command.","Verify the argument name spelling matches the command's arg definition."],"exampleFix":"// before\nawait run('whoami', {})\n// after\nawait run('whoami', { site: 'acme' })","handlingStrategy":"validation","validationCode":"function requireArgs(kwargs: Record<string, unknown>, required: string[]) {\n  const missing = required.filter(k => kwargs[k] === undefined || kwargs[k] === null || kwargs[k] === '');\n  if (missing.length) throw new Error(`Missing required argument(s): ${missing.map(m => `--${m}`).join(', ')}`);\n}\nrequireArgs(kwargs, ['site']);","typeGuard":"function hasValue<T>(v: T | undefined | null | ''): v is T {\n  return v !== undefined && v !== null && v !== '';\n}","tryCatchPattern":"try {\n  await opencli.run(cmd, kwargs);\n} catch (e) {\n  if (/Argument \".+\" is required\\./.test(e.message)) {\n    console.error(`${e.message} ${e.help ?? ''}`);\n    process.exitCode = 2;\n  } else throw e;\n}","preventionTips":["Read the command's arg definitions (--help) and list required flags in your wrapper.","Guard shell variables so empty expansions don't become empty-string flags.","Validate kwargs programmatically before invoking commands from scripts/CI."],"tags":["cli","required-argument","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}