python/cpython · error · ArgumentError

the following arguments are required

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.

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
• ambiguous option: %(option)s could match %(matches)s
• .__call__() not defined
• can't open '%(filename)s': %(error)s
• expected argument

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

Appendix: 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)