"Flag provided but not defined" doesn't give enough details

[coilysiren]

"Flag provided but not defined" doesn't give enough details for end users who aren't specifically aware of how CLIs work. I get a lot of bug reports that are "I got this obscure error message, and I'm not sure what to do".

See also

• Is there a way to allow any arbitrary flags for a particular command? #663
• Misleading user error message when using flags #744

[ghost]

I'd like an opportunity to tackle this one. working on it now

[coilysiren]

@Zohvek yay cool! 🎉

[coilysiren]

Moving this one back to help wanted 📝

[arashout]

I can try working on this, but what kind of error exactly would be more explicit than this?

Something like:
"The flag 'v' was passed but you did not define an associated flag in the configuration for 'v'" ?

I'm not sure that is any better? Do you have any suggestions @lynncyrin ?

[stale]

This issue or PR has been automatically marked as stale because it has not had recent activity. Please add a comment bumping this if you're still interested in it's resolution! Thanks for your help, please let us know if you need anything else.

[coilysiren]

"The flag 'v' was passed but you did not define an associated flag in the configuration for 'v'" ?

This is closer, but still probably not verbose enough. There's also a few words / phrases that are likely to trip people up here, specifically:

• "was passed"
• "define an associated flag"
• "you did not define"

^ those all have meaning for CLI authors, but are likely not very understable for many CLI users. In particular there's the "you did not define", which isn't true from the PoV of users.

Working from those points, here's my suggested error message:

"You input the flag v but the y app does not accept that flag as an input."

the changes look like this:

• "was passed" => "you input"
• "define an associated flag" => "does not accept that flag"
• "you did not define" => "the y app"

[stale]

This issue or PR has been bumped and is no longer marked as stale! Feel free to bump it again in the future, if it's still relevant.

[coilysiren]

I'm also vaguely skeptical that the casual user will know what the word "flag" means, so it might be better to remove that word from the error message entirely. On a related note, the "app" term only likely makes sense if you're a CLI author. So I'm thinking about an error message like this

"You input -v but the CLI y does not accept -v as an input."

[rliebz]

A few examples of existing CLIs with error messages:

• sed: sed: illegal option -- j
• awk: awk: unknown option -j ignored
• vim: Unknown option argument: "-j"
• emacs: Unknown option ‘-j’
• go: flag provided but not defined: -j
• git: unknown option: -j
• python: Unknown option: -j
• pip: no such option: -j
• node: /usr/local/bin/node: bad option: -j
• docker: unknown shorthand flag: 'j' in -j

Fun fact: No CLI that I tried accepted a -j flag.

The word flag is almost always referred to as an option, so we should follow that example.
I don't think things like including the CLI name are necessary, since users already have that information, but a handful of tools do include it.

I'd stick with the most common pattern and probably just do unknown option: -j.

[coilysiren]

I'd stick with the most common pattern and probably just do unknown option: -j

Your appraisal of the landscape is a good one 👍 That said, changing the error message to unknown option: -j would likely lead to a large increase in the amount of time I spent supporting users with this problem 😆

So what I would like to see here is some capability that allows CLI authors to provide their own error messages for all of our errors.

[rliebz]

I personally think there's value in a shorter error message compared to what we currently have. It may be confusing because it offers information that's irrelevant to the person trying to debug, rather than not offering enough context.

Regarding providing different error messages, I agree, that functionality is necessary. It looks like the OnUsageError field should be the current solution, but unfortunately it does not cover all usage scenarios. It handles flag provided but not defined: -fake-flag, flag needs an argument: -arg-flag, invalid value "foo" for flag -int-flag: parse error, but not No help topic for 'fake-cmd'. Not sure what other usage errors might exist.

[stale]

This issue or PR has been automatically marked as stale because it has not had recent activity. Please add a comment bumping this if you're still interested in it's resolution! Thanks for your help, please let us know if you need anything else.

[stale]

Closing this as it has become stale.

[dangspaceiq]

I have an error like this:
Incorrect Usage: flag provided but not defined: -apikey

but the apiKey is provide as requested by the documentation! And I can not find any info of what is really the cause.

[dearchap]

Duplicate of #427