RustPython/RustPython · error · ValueError

conflicting subparser alias: {alias}

Error message

conflicting subparser alias: {alias}

What it means

Raised by _SubParsersAction.add_parser when an entry in aliases=[...] already exists in _name_parser_map. Aliases are stored in the same map as real names, so each alias must be unique among all names and aliases of that subparsers group.

Source

Thrown at Lib/argparse.py:1261

            help=help,
            metavar=metavar)

    def add_parser(self, name, *, deprecated=False, **kwargs):
        # set prog from the existing prefix
        if kwargs.get('prog') is None:
            kwargs['prog'] = '%s %s' % (self._prog_prefix, name)

        # set color
        if kwargs.get('color') is None:
            kwargs['color'] = self._color

        aliases = kwargs.pop('aliases', ())

        if name in self._name_parser_map:
            raise ValueError(f'conflicting subparser: {name}')
        for alias in aliases:
            if alias in self._name_parser_map:
                raise ValueError(f'conflicting subparser alias: {alias}')

        # create a pseudo-action to hold the choice help
        if 'help' in kwargs:
            help = kwargs.pop('help')
            choice_action = self._ChoicesPseudoAction(name, aliases, help)
            self._choices_actions.append(choice_action)
        else:
            choice_action = None

        # create the parser and add it to the map
        parser = self._parser_class(**kwargs)
        if choice_action is not None:
            parser._check_help(choice_action)
        self._name_parser_map[name] = parser

        # make parser available under aliases also
        for alias in aliases:
            self._name_parser_map[alias] = parser

View on GitHub (pinned to aaeab4f754)

Solutions

1. Check each alias against subparsers.choices before registering, and skip or pick another alias on collision.
2. Derive aliases with a scheme guaranteed unique (e.g. first two letters) or assign short forms only manually.

Example fix

# before
subparsers.add_parser('status', aliases=['s'])
# after
taken = set(subparsers.choices)
alias = 'st' if 's' in taken else 's'
subparsers.add_parser('status', aliases=[alias])

def unique_aliases(subparsers, name, candidates):
    taken = set(subparsers.choices) | {name}
    return [c for c in candidates if c not in taken]

When it happens

Trigger: subparsers.add_parser('status', aliases=['s']) after subparsers.add_parser('start', aliases=['s']); any alias equal to an existing command name or previously registered alias.

Common situations: Auto-derived short aliases (first letters) colliding, e.g. 'serve' and 'status' both mapping to 's'; alias tables merged from several modules.

Related errors

• conflicting subparser: {name}
• invalid nargs value
• invalid option name {option_string!r} for BooleanOptionalAct
• nargs for store actions must be != 0; if you have nothing to
• nargs must be %r to supply const

AI-assisted analysis of RustPython/RustPython@aaeab4f754 (2026-08-17). Data as JSON: /api/errors/d4248e04dd5ce2a6. Report an issue: GitHub.