{"id":"c412e805a865563b","repo":"tj/commander.js","slug":"a-default-value-for-a-required-argument-is-never-u","errorCode":null,"errorMessage":"a default value for a required argument is never used: '${argument.name()}'","messagePattern":"a default value for a required argument is never used: '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/command.js","lineNumber":388,"sourceCode":"  /**\n   * Define argument syntax for command, adding a prepared argument.\n   *\n   * @param {Argument} argument\n   * @return {Command} `this` command for chaining\n   */\n  addArgument(argument) {\n    const previousArgument = this.registeredArguments.slice(-1)[0];\n    if (previousArgument?.variadic) {\n      throw new Error(\n        `only the last argument can be variadic '${previousArgument.name()}'`,\n      );\n    }\n    if (\n      argument.required &&\n      argument.defaultValue !== undefined &&\n      argument.parseArg === undefined\n    ) {\n      throw new Error(\n        `a default value for a required argument is never used: '${argument.name()}'`,\n      );\n    }\n    this.registeredArguments.push(argument);\n    return this;\n  }\n\n  /**\n   * Customise or override default help command. By default a help command is automatically added if your command has subcommands.\n   *\n   * @example\n   *    program.helpCommand('help [cmd]');\n   *    program.helpCommand('help [cmd]', 'show help');\n   *    program.helpCommand(false); // suppress default help command\n   *    program.helpCommand(true); // add help command even if no subcommands\n   *\n   * @param {string|boolean} enableOrNameAndArgs - enable with custom name and/or arguments, or boolean to override whether added\n   * @param {string} [description] - custom description","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/command.js#L370-L406","documentation":"Thrown by Command.addArgument() at lib/command.js:383-391 when a required argument (name in `<>`) is given a defaultValue but no custom parser. A required argument is always supplied by the user at runtime, so its default can never apply — the configuration is contradictory and almost always a mistake (the author likely meant optional).","triggerScenarios":"`.argument('<port>', 'port', 3000)` — three-arg form where the third positional is treated as defaultValue when the second isn't a function. Required (`<port>`) + defaultValue present + no parser => throw.","commonSituations":"Author intends an optional argument but writes `<>` instead of `[]`; copy-paste from an optional example into a required declaration; mixing up the overloaded third parameter (parser vs default).","solutions":["Make the argument optional: `.argument('[port]', 'port', 3000)` so the default can apply when omitted.","Or drop the default if the argument truly is required: `.argument('<port>', 'port')`.","If you need both required-ness and a fallback transform, supply a parser as the third arg and the default as the fourth: `.argument('<port>', 'port', Number, 3000)` — though note required+default is still semantically odd."],"exampleFix":"// before (throws)\n.argument('<port>', 'port', 3000)\n\n// after (optional, default applies)\n.argument('[port]', 'port', 3000)","handlingStrategy":"validation","validationCode":"// Reject required+default-without-parser at config-build time\nfunction safeArgument(name, opts) {\n  const required = name.startsWith('<');\n  if (required && 'default' in opts && typeof opts.parser !== 'function') {\n    throw new Error(`required arg '${name}' cannot have a default without a parser`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use [] (optional) whenever you supply a default value.","Remember the overloaded 3rd param: function => parser, else => default.","Add a config-time unit test over argument definitions."],"tags":["commander","argument","default-value","configuration"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}