python/cpython · error · ArgumentError

ambiguous option: %(option)s could match %(matches)s

Error message

ambiguous option: %(option)s could match %(matches)s

What it means

argparse allows abbreviating long options by default (allow_abbrev=True); when a typed prefix (e.g. --ver) matches the prefix of more than one registered option string, the parser cannot disambiguate and raises ArgumentError naming the ambiguous option and the list of candidates. The error is raised inside consume_optional before any value is consumed.

Source

Thrown at Lib/argparse.py:2279

                        raise ArgumentError(action, msg % action_name)

            # take the action if we didn't receive a SUPPRESS value
            # (e.g. from a default)
            if argument_values is not SUPPRESS:
                action(self, namespace, argument_values, option_string)

        # function to convert arg_strings into an optional action
        def consume_optional(start_index):

            # get the optional identified at this index
            option_tuples = option_string_indices[start_index]
            # if multiple actions match, the option string was ambiguous
            if len(option_tuples) > 1:
                options = ', '.join([option_string
                    for action, option_string, sep, explicit_arg in option_tuples])
                args = {'option': arg_strings[start_index], 'matches': options}
                msg = _('ambiguous option: %(option)s could match %(matches)s')
                raise ArgumentError(None, msg % args)

            action, option_string, sep, explicit_arg = option_tuples[0]

            # identify additional optionals in the same arg string
            # (e.g. -xyz is the same as -x -y -z if no args are required)
            match_argument = self._match_argument
            action_tuples = []
            while True:

                # if we found no optional action, skip it
                if action is None:
                    extras.append(arg_strings[start_index])
                    extras_pattern.append('O')
                    return start_index + 1

                # if there is an explicit argument, try to match the
                # optional's string arguments to only this
                if explicit_arg is not None:

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Type the full option name (e.g. --verbose) instead of the abbreviation.
2. Construct ArgumentParser(allow_abbrev=False) to disable prefix matching entirely and force exact names.
3. Rename one of the colliding options so no shared-prefix ambiguity exists (e.g. --verbosity vs --version).

Example fix

# before
parser = argparse.ArgumentParser()  # allow_abbrev defaults to True
parser.add_argument('--verbose', action='store_true')
parser.add_argument('--version', action='store_true')
# `prog --ver` -> ambiguous option: --ver could match --verbose --version

# after
parser = argparse.ArgumentParser(allow_abbrev=False)
parser.add_argument('--verbose', action='store_true')
parser.add_argument('--version', action='store_true')

def is_unambiguous(parser, token):
    if not token.startswith('--') or '=' in token or len(token) <= 2:
        return True
    prefix = token[2:]
    matches = [s for a in parser._actions for s in a.option_strings
               if s.startswith('--' + prefix)]
    return len(matches) == 1

try:
    args = parser.parse_args(argv)
except argparse.ArgumentError as e:
    if 'ambiguous option' in str(e):
        print('use the full option name; abbreviations are disabled')

When it happens

Trigger: Two options share a prefix (e.g. --verbose and --version) and the user types the common prefix (--ver). Also triggered by an exact-looking option that is itself only a prefix of longer options, and when dynamically added subparser options introduce a second match for a previously unambiguous abbreviation.

Common situations: Adding --version to a parser that already has --verbose (the classic case); shell tab-completion or scripts emitting shortened flags; multi-command CLIs where subparsers accumulate same-prefix options.

Related errors

• invalid nargs value
• .__call__() not defined
• 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 python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/c0afb614688dac10. Report an issue: GitHub.