tj/commander.js · error · Error

Command alias can't be the same as its name

Error message

Command alias can't be the same as its name

What it means

Thrown by Command.alias() at lib/command.js:2277-2278 when the alias being added equals the command's own `_name`. An alias identical to the name is redundant and would confuse dispatch/help/conflict detection (knownBy would list the same string twice). Note the method supports an indirection: if the last registered command is an executable subcommand, the alias applies to it, not to `this`.

Source

Thrown at lib/command.js:2278

   * @return {(string|Command)}
   */

  alias(alias) {
    if (alias === undefined) return this._aliases[0]; // just return first, for backwards compatibility

    /** @type {Command} */
    // eslint-disable-next-line @typescript-eslint/no-this-alias
    let command = this;
    if (
      this.commands.length !== 0 &&
      this.commands[this.commands.length - 1]._executableHandler
    ) {
      // assume adding alias for last added executable subcommand, rather than this
      command = this.commands[this.commands.length - 1];
    }

    if (alias === command._name)
      throw new Error("Command alias can't be the same as its name");
    const matchingCommand = this.parent?._findCommand(alias);
    if (matchingCommand) {
      // c.f. _registerCommand
      const existingCmd = [matchingCommand.name()]
        .concat(matchingCommand.aliases())
        .join('|');
      throw new Error(
        `cannot add alias '${alias}' to command '${this.name()}' as already have command '${existingCmd}'`,
      );
    }

    command._aliases.push(alias);
    return this;
  }

  /**
   * Set aliases for the command.
   *

View on GitHub (pinned to ba6d13ddb4)

Solutions

1. Pick an alias different from the name: `cmd.alias('b')` for a 'build' command.
2. If you don't actually need an alias, remove the .alias() call.
3. When generating aliases programmatically, filter out the command name: `names.filter(n => n !== cmd.name()).forEach(n => cmd.alias(n))`.

Example fix

// before (throws)
program.command('build').alias('build');

// after
program.command('build').alias('b');

function safeAlias(cmd, alias) {
  if (alias === cmd.name()) {
    throw new Error(`alias '${alias}' must differ from command name`);
  }
  return cmd.alias(alias);
}

When it happens

Trigger: `new Command('build').alias('build')`, or dynamic `cmd.alias(cmd.name())`. Also when an alias is computed from config and happens to equal the name.

Common situations: Generating aliases from a list that includes the command's own name; copy-paste where alias mirrors name; refactor that renamed a command but left an alias equal to the old name which is now the new name.

Related errors

• cannot add command '${newCmd}' as already have command '${ex
• cannot add alias '${alias}' to command '${this.name()}' as a
• Not a number.
• Not a number.
• Allowed choices are ${this.argChoices.join(', ')}.

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