python/cpython · error · ArgumentError

the following arguments are required: %s

Error message

the following arguments are required: %s

What it means

After parsing completes, argparse collects required actions (required=True options or positionals without defaults) that never appeared in seen_actions and were not satisfied; if the list is non-empty it raises ArgumentError listing every missing argument name joined by commas. This is the standard 'you forgot an argument' failure of parse_args.

Source

Thrown at Lib/argparse.py:2487

        required_actions = []
        for action in self._actions:
            if action not in seen_actions:
                if action.required:
                    required_actions.append(_get_action_name(action))
                else:
                    # Convert action default now instead of doing it before
                    # parsing arguments to avoid calling convert functions
                    # twice (which may fail) if the argument was given, but
                    # only if it was defined already in the namespace
                    if (action.default is not None and
                        isinstance(action.default, str) and
                        hasattr(namespace, action.dest) and
                        action.default is getattr(namespace, action.dest)):
                        setattr(namespace, action.dest,
                                self._get_value(action, action.default))

        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

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Supply every missing argument listed in the error message.
2. If the argument is genuinely optional, remove required=True or provide a sensible default.
3. Use nargs='?' with a default for positionals that may be absent.
4. Construct with exit_on_error=False and catch argparse.ArgumentError to surface a custom usage message in API contexts.

Example fix

# before
parser.add_argument('--out', required=True)
parser.parse_args([])  # error: the following arguments are required: --out

# after
parser.add_argument('--out', default='out.txt')

def missing_required(parser, argv):
    prov = {a.split('=')[0] for a in argv}
    missing = [s or a.dest for a in parser._actions
               if a.required and not (set(a.option_strings) & prov)
               and not a.option_strings]  # required positionals
    return missing

try:
    args = parser.parse_args(argv)
except argparse.ArgumentError as e:
    if 'arguments are required' in str(e):
        print(parser.format_usage(), file=sys.stderr)
        sys.exit(2)

When it happens

Trigger: An option declared with required=True (add_argument('--out', required=True)) is omitted; a positional with nargs='+' is omitted; a required argument inside a parser is skipped because the user only passed --help-adjacent flags or relied on a default that was never set.

Common situations: Scripts invoked by cron/ci with incomplete argument lists; new required options added in a later version breaking old invocations; wrappers that conditionally forward arguments and drop a required one.

Related errors

• one of the arguments %s is required
• 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

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