python/cpython · error · ArgumentError

one of the arguments %s is required

Error message

one of the arguments %s is required

What it means

Raised when a mutually exclusive group was created with required=True but no member of that group appeared among the seen non-default actions after parsing. argparse iterates the group's actions, and if none was used it raises ArgumentError listing the group's option names (excluding those whose help is SUPPRESS).

Source

Thrown at Lib/argparse.py:2503

        if required_actions:
            raise ArgumentError(None, _('the following arguments are required: %s') %
                       ', '.join(required_actions))

        # make sure all required groups had one option present
        for group in self._mutually_exclusive_groups:
            if group.required:
                for action in group._group_actions:
                    if action in seen_non_default_actions:
                        break

                # if no actions were used, report the error
                else:
                    names = [_get_action_name(action)
                             for action in group._group_actions
                             if action.help is not SUPPRESS]
                    msg = _('one of the arguments %s is required')
                    raise ArgumentError(None, msg % ' '.join(names))

        # return the updated namespace and the extra arguments
        return namespace, extras

    def _read_args_from_files(self, arg_strings):
        # expand arguments referencing files
        new_arg_strings = []
        for arg_string in arg_strings:

            # for regular arguments, just add them back into the list
            if not arg_string or arg_string[0] not in self.fromfile_prefix_chars:
                new_arg_strings.append(arg_string)

            # replace arguments referencing files with the file content
            else:
                try:
                    with open(arg_string[1:],
                              encoding=_sys.getfilesystemencoding(),

View on GitHub (pinned to bc6749cc3b)

Solutions

  1. Supply exactly one of the options listed in the error message.
  2. If 'none' is acceptable, create the group without required=True and handle the absence in code.
  3. If exactly-one semantics are wrong, replace the group with a single required option and choices.

Example fix

# before
g = parser.add_mutually_exclusive_group(required=True)
g.add_argument('--file'); g.add_argument('--url')
parser.parse_args([])  # error: one of the arguments --file --url is required

# after
g = parser.add_mutually_exclusive_group(required=False)
g.add_argument('--file'); g.add_argument('--url')
Defensive patterns

Strategy: validation

Validate before calling

def required_group_satisfied(parser, argv):
    prov = {a.split('=')[0] for a in argv}
    for g in parser._mutually_exclusive_groups:
        if not g.required:
            continue
        names = {s for a in g._group_actions for s in a.option_strings}
        if not (names & prov):
            return sorted(names)
    return None

Try / catch

try:
    args = parser.parse_args(argv)
except argparse.ArgumentError as e:
    if 'is required' in str(e):
        print('choose one of the listed options or rerun with --help')

Prevention

When it happens

Trigger: g = parser.add_mutually_exclusive_group(required=True); g.add_argument('--foo'); g.add_argument('--bar'); the user supplies neither --foo nor --bar. Also fires when the only supplied member equals its default (defaults do not count as 'seen non-default').

Common situations: Input-source groups like (--file | --url | --stdin) where exactly one must be given; refactoring a single required option into an either/or group and forgetting to update callers; frontends that hide both flags behind an optional GUI toggle.

Related errors

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/893b07bdd74fc56d. Report an issue: GitHub.