tj/commander.js · error · Error

outputHelp callback must return a string or a Buffer

Error message

outputHelp callback must return a string or a Buffer

What it means

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().

Source

Thrown at lib/command.js:2546

    const eventContext = {
      error: outputContext.error,
      write: outputContext.write,
      command: this,
    };

    this._getCommandAndAncestors()
      .reverse()
      .forEach((command) => command.emit('beforeAllHelp', eventContext));
    this.emit('beforeHelp', eventContext);

    let helpInformation = this.helpInformation({ error: outputContext.error });
    if (deprecatedCallback) {
      helpInformation = deprecatedCallback(helpInformation);
      if (
        typeof helpInformation !== 'string' &&
        !Buffer.isBuffer(helpInformation)
      ) {
        throw new Error('outputHelp callback must return a string or a Buffer');
      }
    }
    outputContext.write(helpInformation);

    if (this._getHelpOption()?.long) {
      this.emit(this._getHelpOption().long); // deprecated
    }
    this.emit('afterHelp', eventContext);
    this._getCommandAndAncestors().forEach((command) =>
      command.emit('afterAllHelp', eventContext),
    );
  }

  /**
   * You can pass in flags and a description to customise the built-in help option.
   * Pass in false to disable the built-in help option.
   *
   * @example

View on GitHub (pinned to ba6d13ddb4)

Solutions

1. Make the callback return the (possibly modified) help string or a Buffer: program.outputHelp((help) => help.toUpperCase()).
2. Migrate to the supported API: register text with program.addHelpText('after', () => '...') and call program.outputHelp() with no function argument.
3. If you only need help written somewhere non-default, configure program.configureOutput({ writeOut }) instead of transforming inside outputHelp.
4. If you must keep the callback, wrap it so a missing/invalid return falls back to the original help text.

Example fix

// before
program.outputHelp((help) => { console.log(help); }); // returns undefined -> throws

// after
program.outputHelp((help) => help); // returns string

// or migrate to the supported API
program.addHelpText('after', '\nSee https://example.com/docs');
program.outputHelp();

// Wrap any outputHelp callback so a bad return type cannot reach Commander.
const { Buffer } = require('node:buffer');
function safeHelpCallback(fn) {
  return (help) => {
    const out = fn(help);
    if (typeof out !== 'string' && !Buffer.isBuffer(out)) {
      throw new TypeError(
        'outputHelp callback must return a string or a Buffer (got ' + typeof out + ')'
      );
    }
    return out;
  };
}
// usage: program.outputHelp(safeHelpCallback((help) => help.toUpperCase()));

const { Buffer } = require('node:buffer');
function isStringOrBuffer(v) {
  return typeof v === 'string' || Buffer.isBuffer(v);
}

When it happens

Trigger: 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').

Common situations: 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.

Related errors

• Unexpected value for position to addHelpText. Expecting one
• Not a number.
• Not a number.
• Allowed choices are ${this.argChoices.join(', ')}.
• Command passed to .addCommand() must have a name - specify t

AI-assisted analysis of tj/commander.js@ba6d13ddb4 (2026-08-03). Data as JSON: /data/errors/5c7eef2223d4d815.json. Report an issue: GitHub.