Undocumented exception: argparse add_argument(action='store_true', metavar='...') raises TypeError

Documentation

Not 100% sure whether this is a bug or a documentation error, but the behavior is reasonable, so filing this as a documentation issue for now.

>>> from argparse import ArgumentParser
>>> parser = ArgumentParser()
>>> parser.add_argument('-v', metavar='VERBOSE', dest='verbose', action='store_true')
Traceback (most recent call last):
  File "<python-input-3>", line 1, in <module>
    parser.add_argument('-v', metavar='VERBOSE', dest='verbose', action='store_true')
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib64/python3.14/argparse.py", line 1539, in add_argument
    action = action_class(**kwargs)
TypeError: _StoreTrueAction.__init__() got an unexpected keyword argument 'metavar'

There is no indication in the documentation that this combination will raise an exception.

(FWIW, this behavior is inconsistent with action='store_const', which silently swallows metavar.)

AI Usage

Claude Code, with Opus 4.8, was used to identify and analyze this issue.

Linked PRs

• gh-156620