{"id":"b04a145b01a5239f","repo":"tj/commander.js","slug":"unexpected-value-for-position-to-addhelptext-expe","errorCode":null,"errorMessage":"Unexpected value for position to addHelpText.\nExpecting one of '${allowedValues.join(\"', '\")}'","messagePattern":"Unexpected value for position to addHelpText\\.\nExpecting one of '(.+?)'","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/command.js","lineNumber":2673,"sourceCode":"   * @property {Command} command\n   * @property {function} write\n   */\n\n  /**\n   * Add additional text to be displayed with the built-in help.\n   *\n   * Position is 'before' or 'after' to affect just this command,\n   * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.\n   *\n   * @param {string} position - before or after built-in help\n   * @param {(string | Function)} text - string to add, or a function returning a string\n   * @return {Command} `this` command for chaining\n   */\n\n  addHelpText(position, text) {\n    const allowedValues = ['beforeAll', 'before', 'after', 'afterAll'];\n    if (!allowedValues.includes(position)) {\n      throw new Error(`Unexpected value for position to addHelpText.\nExpecting one of '${allowedValues.join(\"', '\")}'`);\n    }\n\n    const helpEvent = `${position}Help`;\n    this.on(helpEvent, (/** @type {HelpTextEventContext} */ context) => {\n      let helpStr;\n      if (typeof text === 'function') {\n        helpStr = text({ error: context.error, command: context.command });\n      } else {\n        helpStr = text;\n      }\n      // Ignore falsy value when nothing to output.\n      if (helpStr) {\n        context.write(`${helpStr}\\n`);\n      }\n    });\n    return this;\n  }","sourceCodeStart":2655,"sourceCodeEnd":2691,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/command.js#L2655-L2691","documentation":"Thrown by addHelpText(position, text) when position is not one of the four allowed strings: 'beforeAll', 'before', 'after', 'afterAll'. The check is a literal includes() against that allow-list at line 2672, so any other value (wrong case, typo, synonyms like 'top'/'start') is rejected. It is a plain Error raised at registration time, before any help is ever rendered.","triggerScenarios":"Calling program.addHelpText('top', '...'), program.addHelpText('Before', '...') (wrong case), program.addHelpText('start', '...'), or passing a value computed from config/variable that does not exactly match one of the four allowed positions.","commonSituations":"Typos or inconsistent casing ('afterall' vs 'afterAll'); guessing a position name instead of checking the docs; driving addHelpText from a user-supplied config key; copy-paste from a different CLI library that uses different position names.","solutions":["Use exactly one of: 'beforeAll', 'before', 'after', 'afterAll' (case-sensitive).","If the position comes from config, validate it against the allow-list before calling addHelpText.","For text above all commands use 'beforeAll'; for text after everything use 'afterAll'; for a single command use 'before'/'after'."],"exampleFix":"// before\nprogram.addHelpText('top', 'My Tool v2.0');\n\n// after\nprogram.addHelpText('beforeAll', 'My Tool v2.0');","handlingStrategy":"validation","validationCode":"const HELP_POSITIONS = ['beforeAll', 'before', 'after', 'afterAll'];\nfunction addHelpTextSafe(cmd, position, text) {\n  if (!HELP_POSITIONS.includes(position)) {\n    throw new Error(\n      `addHelpText position must be one of ${HELP_POSITIONS.join(', ')} (got ${JSON.stringify(position)})`\n    );\n  }\n  return cmd.addHelpText(position, text);\n}","typeGuard":"const HELP_POSITIONS = ['beforeAll', 'before', 'after', 'afterAll'];\nfunction isHelpPosition(v) {\n  return typeof v === 'string' && HELP_POSITIONS.includes(v);\n}","tryCatchPattern":null,"preventionTips":["Keep a shared HELP_POSITIONS constant so call sites and validation never drift from the allowed set.","Treat the position as an enum in your config schema, not a free-form string.","Add a smoke test that registers help text for each position you use."],"tags":["help","validation","commander"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}