{"record":{"id":"c0afb614688dac10","repo":"python/cpython","slug":"ambiguous-option-option-s-could-match-matches","errorCode":null,"errorMessage":"ambiguous option: %(option)s could match %(matches)s","messagePattern":"ambiguous option: (.+?) could match (.+?)","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"Lib/argparse.py","lineNumber":2279,"sourceCode":"                        raise ArgumentError(action, msg % action_name)\n\n            # take the action if we didn't receive a SUPPRESS value\n            # (e.g. from a default)\n            if argument_values is not SUPPRESS:\n                action(self, namespace, argument_values, option_string)\n\n        # function to convert arg_strings into an optional action\n        def consume_optional(start_index):\n\n            # get the optional identified at this index\n            option_tuples = option_string_indices[start_index]\n            # if multiple actions match, the option string was ambiguous\n            if len(option_tuples) > 1:\n                options = ', '.join([option_string\n                    for action, option_string, sep, explicit_arg in option_tuples])\n                args = {'option': arg_strings[start_index], 'matches': options}\n                msg = _('ambiguous option: %(option)s could match %(matches)s')\n                raise ArgumentError(None, msg % args)\n\n            action, option_string, sep, explicit_arg = option_tuples[0]\n\n            # identify additional optionals in the same arg string\n            # (e.g. -xyz is the same as -x -y -z if no args are required)\n            match_argument = self._match_argument\n            action_tuples = []\n            while True:\n\n                # if we found no optional action, skip it\n                if action is None:\n                    extras.append(arg_strings[start_index])\n                    extras_pattern.append('O')\n                    return start_index + 1\n\n                # if there is an explicit argument, try to match the\n                # optional's string arguments to only this\n                if explicit_arg is not None:","sourceCodeStart":2261,"sourceCodeEnd":2297,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/argparse.py#L2261-L2297","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Type the full option name (e.g. --verbose) instead of the abbreviation.","Construct ArgumentParser(allow_abbrev=False) to disable prefix matching entirely and force exact names.","Rename one of the colliding options so no shared-prefix ambiguity exists (e.g. --verbosity vs --version)."],"exampleFix":"# before\nparser = argparse.ArgumentParser()  # allow_abbrev defaults to True\nparser.add_argument('--verbose', action='store_true')\nparser.add_argument('--version', action='store_true')\n# `prog --ver` -> ambiguous option: --ver could match --verbose --version\n\n# after\nparser = argparse.ArgumentParser(allow_abbrev=False)\nparser.add_argument('--verbose', action='store_true')\nparser.add_argument('--version', action='store_true')","handlingStrategy":"validation","validationCode":"def is_unambiguous(parser, token):\n    if not token.startswith('--') or '=' in token or len(token) <= 2:\n        return True\n    prefix = token[2:]\n    matches = [s for a in parser._actions for s in a.option_strings\n               if s.startswith('--' + prefix)]\n    return len(matches) == 1","typeGuard":null,"tryCatchPattern":"try:\n    args = parser.parse_args(argv)\nexcept argparse.ArgumentError as e:\n    if 'ambiguous option' in str(e):\n        print('use the full option name; abbreviations are disabled')","preventionTips":["Set ArgumentParser(allow_abbrev=False) in production CLIs so abbreviations fail deterministically.","Avoid registering options that share prefixes (--verbose/--version is the classic trap).","Never generate shortened flag names programmatically; always emit full option strings."],"tags":["argparse","cli","abbreviation","ambiguous-option"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}