{"id":"5c7eef2223d4d815","repo":"tj/commander.js","slug":"outputhelp-callback-must-return-a-string-or-a-buff","errorCode":null,"errorMessage":"outputHelp callback must return a string or a Buffer","messagePattern":"outputHelp callback must return a string or a Buffer","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/command.js","lineNumber":2546,"sourceCode":"    const eventContext = {\n      error: outputContext.error,\n      write: outputContext.write,\n      command: this,\n    };\n\n    this._getCommandAndAncestors()\n      .reverse()\n      .forEach((command) => command.emit('beforeAllHelp', eventContext));\n    this.emit('beforeHelp', eventContext);\n\n    let helpInformation = this.helpInformation({ error: outputContext.error });\n    if (deprecatedCallback) {\n      helpInformation = deprecatedCallback(helpInformation);\n      if (\n        typeof helpInformation !== 'string' &&\n        !Buffer.isBuffer(helpInformation)\n      ) {\n        throw new Error('outputHelp callback must return a string or a Buffer');\n      }\n    }\n    outputContext.write(helpInformation);\n\n    if (this._getHelpOption()?.long) {\n      this.emit(this._getHelpOption().long); // deprecated\n    }\n    this.emit('afterHelp', eventContext);\n    this._getCommandAndAncestors().forEach((command) =>\n      command.emit('afterAllHelp', eventContext),\n    );\n  }\n\n  /**\n   * You can pass in flags and a description to customise the built-in help option.\n   * Pass in false to disable the built-in help option.\n   *\n   * @example","sourceCodeStart":2528,"sourceCodeEnd":2564,"githubUrl":"https://github.com/tj/commander.js/blob/ba6d13ddb4243e5913367734f8c159089ffe7834/lib/command.js#L2528-L2564","documentation":"Thrown by outputHelp() when its first argument is a function (a deprecated calling convention from older Commander releases). Commander treats that function as a transformation callback over the already-rendered help text and requires it to return a string or a Buffer; any other return type (undefined, number, object, array) triggers this error. It is a plain Error, not a CommanderError, so it is not auto-formatted by Commander's own error handling. The supported replacement is addHelpText().","triggerScenarios":"Calling program.outputHelp(fn) where fn returns undefined (e.g. a callback whose last statement is console.log, or an arrow function with a block body and no return), or where fn returns a non-string/non-Buffer such as a number or an object. The throw happens synchronously inside outputHelp at line 2546 when the deprecated callback path is taken (typeof contextOptions === 'function').","commonSituations":"Code migrated from an older Commander version that used the outputHelp(callback) signature; a callback that mutates help via side effects (writing to stdout itself) instead of returning the text; forgetting the return keyword in {(help) => { ... }} arrow functions; refactors that changed the callback's return value.","solutions":["Make the callback return the (possibly modified) help string or a Buffer: program.outputHelp((help) => help.toUpperCase()).","Migrate to the supported API: register text with program.addHelpText('after', () => '...') and call program.outputHelp() with no function argument.","If you only need help written somewhere non-default, configure program.configureOutput({ writeOut }) instead of transforming inside outputHelp.","If you must keep the callback, wrap it so a missing/invalid return falls back to the original help text."],"exampleFix":"// before\nprogram.outputHelp((help) => { console.log(help); }); // returns undefined -> throws\n\n// after\nprogram.outputHelp((help) => help); // returns string\n\n// or migrate to the supported API\nprogram.addHelpText('after', '\\nSee https://example.com/docs');\nprogram.outputHelp();","handlingStrategy":"validation","validationCode":"// Wrap any outputHelp callback so a bad return type cannot reach Commander.\nconst { Buffer } = require('node:buffer');\nfunction safeHelpCallback(fn) {\n  return (help) => {\n    const out = fn(help);\n    if (typeof out !== 'string' && !Buffer.isBuffer(out)) {\n      throw new TypeError(\n        'outputHelp callback must return a string or a Buffer (got ' + typeof out + ')'\n      );\n    }\n    return out;\n  };\n}\n// usage: program.outputHelp(safeHelpCallback((help) => help.toUpperCase()));","typeGuard":"const { Buffer } = require('node:buffer');\nfunction isStringOrBuffer(v) {\n  return typeof v === 'string' || Buffer.isBuffer(v);\n}","tryCatchPattern":null,"preventionTips":["Prefer the supported addHelpText(position, text) API over passing a function to outputHelp.","If you keep the callback, always return the help value; avoid block-body arrows that rely on side effects.","Add a unit test that calls outputHelp with your callback and asserts it does not throw."],"tags":["help","deprecation","callback","commander"],"analyzedSha":"ba6d13ddb4243e5913367734f8c159089ffe7834","analyzedAt":"2026-08-03T20:26:04.326Z","schemaVersion":2}