What steps will reproduce the problem?

parser = argparse.ArgumentParser()	
parser.add_argument('--foo', nargs=2, metavar=('X','Y','Z'))
parser.parse_args(['-h'])

The error dosn't show up until help is formatted.

Giving any incorrect length of metavar will produce the problem, which
includes a tuple whos length doesn't match a numerical value, more than two metavars to '*' or '+', and more than one metavar to '?'. Furthermore, a tuple of length one causes the error when nargs is greater than 1, '*', or '+'.

What is the expected output? What do you see instead?

When the help is displayed, you get:

TypeError: not all arguments converted during string formatting

Or a similar error message for other cases.

It would be expected that the error message would be more specific. The
error should definitely be raised when add_argument is called, rather than later.

There should be a test that does something like:

    for meta in ('X', ('X',), ('X','Y'), ('X','Y','Z')):
        for n in (1, 2, 3, '?', '+', '*'):
            parser = argparse.ArgumentParser()
            parser.add_argument('--foo', nargs=n, metavar=meta)
            parser.format_help()

and makes sure that the error shows up in add_argument, not format_help.

I'm attaching a unit test patch that does something vaguely like Steven suggests.  It definitely needs review.

Also, I'm assuming that it's OK to specify *fewer* metavars than nargs, just not more... but I'm not sure about that.

You can specify either 1 or N. So for n=3, you can specify metavar="X" or metavar=("X", "Y", "Z") but not metavar=("X", "Y"). The special nargs value "?" always takes only one, while "*" and "+" always take two. (This makes sense if you think about how they're formatted, e.g. "X [X ...]".)

Thanks for the correction, Steven.  This unit test matches your description.  Use it instead of my earlier submission.

For kicks, I just took a look at this old, forgotten issue.  I agree with the submitter that add_argument() should fail if nargs and metavar do not match, instead of having format_help() raise the exception later on.

I've attached a patch (issue9348_patch_v01.txt) with a proposed fix and associated test cases.  The drawback of my approach is that if a custom HelpFormatter is used which has different semantics for metavar it could cause add_argument() to incorrectly reject the metavar value.  I'm not sure how common that is though.

New changeset c89db9b36ea6 by Steven Bethard in branch '3.2':
Issue #9348: Raise an early error if argparse nargs and metavar don't match.
http://hg.python.org/cpython/rev/c89db9b36ea6

New changeset b93a50bb74f2 by Steven Bethard in branch 'default':
Issue #9348: Raise an early error if argparse nargs and metavar don't match. (Merge from 3.2.)
http://hg.python.org/cpython/rev/b93a50bb74f2

New changeset 4bb651eb7539 by Steven Bethard in branch '2.7':
Issue #9348: Raise an early error if argparse nargs and metavar don't match. (Merge from 3.2.)
http://hg.python.org/cpython/rev/4bb651eb7539

Thanks for the patch. I used something similar to what you proposed, but instead of creating a local formatter, I just call self._get_formatter() if it exists.

Awesome, thanks for committing the patch.  Glad I could help.

This adds overhead, since it creates a formatter and uses it for formatting only for validation purposes.

I think it is better to only have the error when the formatter is actually used (i.e. the help is displayed - which is not the typical use case, and it should be optimized for not displaying the help (i.e. only parsing args)).
The error could be more specific than before/initially though, of course.