{"record":{"id":"49f7f527cd5c90c1","repo":"can1357/oh-my-pi","slug":"missing-required-argument-argname","errorCode":null,"errorMessage":"Missing required argument: ${argName}","messagePattern":"Missing required argument: (.+?)","errorType":"validation","errorClass":"CliUsageError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/cli.ts","lineNumber":274,"sourceCode":"\t\t\t}\n\t\t}\n\n\t\t// Map positionals to named args in declaration order and validate\n\t\tconst args: Record<string, unknown> = {};\n\t\tlet posIdx = 0;\n\t\tfor (const [argName, desc] of Object.entries(argDefs)) {\n\t\t\tif (desc.multiple) {\n\t\t\t\tconst val = positionals.slice(posIdx);\n\t\t\t\targs[argName] = val.length > 0 ? val : undefined;\n\t\t\t\tposIdx = positionals.length;\n\t\t\t} else {\n\t\t\t\tconst val = positionals[posIdx];\n\t\t\t\targs[argName] = val;\n\t\t\t\tposIdx++;\n\t\t\t}\n\t\t\t// Validate required\n\t\t\tif (desc.required && args[argName] === undefined) {\n\t\t\t\tthrow new CliUsageError(`Missing required argument: ${argName}`);\n\t\t\t}\n\t\t\t// Validate options constraint\n\t\t\tconst argVal = args[argName];\n\t\t\tif (argVal !== undefined && desc.options && typeof argVal === \"string\") {\n\t\t\t\tif (!desc.options.includes(argVal)) {\n\t\t\t\t\tthrow new CliUsageError(\n\t\t\t\t\t\t`Expected ${argName} to be one of: ${[...desc.options].join(\", \")}; got \"${argVal}\"`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn { flags, args, argv: positionals } as never;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Help rendering","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/utils/src/cli.ts#L256-L292","documentation":"parse() maps positional arguments to declared arg names in order; if a positional declared `required: true` has no corresponding value on the command line, it throws a CliUsageError naming the missing argument.","triggerScenarios":"Calling parse() with too few positionals, e.g. omitting the <file> positional a command declares as required.","commonSituations":"Copy-pasting a command and dropping a path, scripts passing an empty variable that the shell drops as an argument, or command signatures changed to require an argument between versions.","solutions":["Supply the missing positional argument in declaration order.","Quote arguments so empty/space-containing values are not dropped by the shell.","Check --help to see the required positional layout.","Make the argument optional (required: false) with a default if it should be omittable."],"exampleFix":"// before\ncli.parse(['--verbose']); // Missing required argument: file\n// after\ncli.parse(['--verbose', 'src/index.ts']);","handlingStrategy":"validation","validationCode":"// positionals: [<file>] required\nconst positionalCount = argv.filter(a => !a.startsWith('--')).length;\nif (positionalCount < 1) throw new Error('Usage: omp <file>');","typeGuard":null,"tryCatchPattern":"try {\n  const { file } = cli.parse(argv);\n} catch (err) {\n  if (err instanceof CliUsageError && err.message.startsWith('Missing required argument')) {\n    console.error(`Usage: ${usageLine}`);\n    process.exitCode = 2;\n    return;\n  }\n  throw err;\n}","preventionTips":["Quote arguments so empty shell variables don't drop positionals.","Pass required positionals in declaration order.","Guard scripts: ${1:?missing file argument} for required shell args."],"tags":["cli","validation","positional-args"],"backgroundTag":"missing-required-argument","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}