{"id":"6e00cd7be32e4a87","repo":"tj/commander.js","slug":"first-parameter-to-parse-must-be-array-or-undefine","errorCode":null,"errorMessage":"first parameter to parse must be array or undefined","messagePattern":"first parameter to parse must be array or undefined","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/command.js","lineNumber":994,"sourceCode":"    let source;\n    this._getCommandAndAncestors().forEach((cmd) => {\n      if (cmd.getOptionValueSource(key) !== undefined) {\n        source = cmd.getOptionValueSource(key);\n      }\n    });\n    return source;\n  }\n\n  /**\n   * Get user arguments from implied or explicit arguments.\n   * Side-effects: set _scriptPath if args included script. Used for default program name, and subcommand searches.\n   *\n   * @private\n   */\n\n  _prepareUserArgs(argv, parseOptions) {\n    if (argv !== undefined && !Array.isArray(argv)) {\n      throw new Error('first parameter to parse must be array or undefined');\n    }\n    parseOptions = parseOptions || {};\n\n    // auto-detect argument conventions if nothing supplied\n    if (argv === undefined && parseOptions.from === undefined) {\n      if (process.versions?.electron) {\n        parseOptions.from = 'electron';\n      }\n      // check node specific options for scenarios where user CLI args follow executable without scriptname\n      const execArgv = process.execArgv ?? [];\n      if (\n        execArgv.includes('-e') ||\n        execArgv.includes('--eval') ||\n        execArgv.includes('-p') ||\n        execArgv.includes('--print')\n      ) {\n        parseOptions.from = 'eval'; // internal usage, not documented\n      }","sourceCodeStart":976,"sourceCodeEnd":1012,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/command.js#L976-L1012","documentation":"Thrown by Command._prepareUserArgs() at lib/command.js:993-995 when the first argument to parse() (argv) is neither undefined nor an array. parse() expects either no argument (use process.argv) or a string array; anything else (a string, an object, a number) is rejected before any slicing/detection logic runs.","triggerScenarios":"`program.parse('--foo bar')` (string instead of array), `program.parse({})`, `program.parse(42)`. Also `program.parse(process.argv.slice(2).join(' '))`.","commonSituations":"Treating argv as a single string and forgetting to split; passing a config object where argv was expected; spread/operator mistakes that collapse the array; porting from a CLI library that accepted a string.","solutions":["Pass an array of strings: `program.parse(['--foo','bar'], { from: 'user' })`.","Or pass nothing to use process.argv: `program.parse()`.","If you have a string, split first: `program.parse(str.split(/\\s+/), { from: 'user' })` — but prefer a real shell-tokenizing library to respect quoting."],"exampleFix":"// before (throws)\nprogram.parse('--foo bar');\n\n// after\nprogram.parse(['--foo', 'bar'], { from: 'user' });","handlingStrategy":"type-guard","validationCode":"function safeParse(cmd, argv) {\n  if (argv !== undefined && !Array.isArray(argv)) {\n    throw new TypeError('parse argv must be undefined or string[]');\n  }\n  return cmd.parse(argv);\n}","typeGuard":"function isArgv(v: unknown): v is string[] | undefined {\n  return v === undefined || (Array.isArray(v) && v.every(x => typeof x === 'string'));\n}","tryCatchPattern":null,"preventionTips":["Always pass either nothing or a string[] to parse().","If you have a string, tokenize with a shell-parsing library first.","Add a TS overload or runtime guard at the boundary."],"tags":["commander","parse","argv","api-misuse"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}