Title: Inconsistent and unclear error messaging · Issue #10056 · PowerShell/PowerShell · GitHub
Open Graph Title: Inconsistent and unclear error messaging · Issue #10056 · PowerShell/PowerShell
X Title: Inconsistent and unclear error messaging · Issue #10056 · PowerShell/PowerShell
Description: When a user provides an invalid value to a parameter, the error message that they receive should be crystal clear. Today, that is not the case. For example, consider these empty command definitions: function Test-Mandatory { param( [Para...
Open Graph Description: When a user provides an invalid value to a parameter, the error message that they receive should be crystal clear. Today, that is not the case. For example, consider these empty command definitions...
X Description: When a user provides an invalid value to a parameter, the error message that they receive should be crystal clear. Today, that is not the case. For example, consider these empty command definitions...
Opengraph URL: https://github.com/PowerShell/PowerShell/issues/10056
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Inconsistent and unclear error messaging","articleBody":"When a user provides an invalid value to a parameter, the error message that they receive should be crystal clear. Today, that is not the case. For example, consider these empty command definitions:\r\n\r\n```powershell\r\nfunction Test-Mandatory {\r\n param(\r\n [Parameter(Mandatory, ParameterSetName='StringTest')]\r\n [string]\r\n $String,\r\n\r\n [Parameter(Mandatory, ParameterSetName='ObjectTest')]\r\n [object]\r\n $Object\r\n )\r\n}\r\n\r\nfunction Test-Validator {\r\n param(\r\n [ValidateNotNullOrEmpty()]\r\n [string]\r\n $String,\r\n\r\n [ValidateNotNull()]\r\n [object]\r\n $Object\r\n )\r\n}\r\n```\r\n\r\nWhen a parameter is marked as `Mandatory`, if it's a string, it cannot be empty. If it's a non-value type object, it cannot be null. That's built in behavior. Command authors can also add `ValidatNotNullOrEmpty` or `ValidateNotNull` validators that ensure that a parameter is not null or empty, or not null, respectively. These are more or less the same thing: logic to ensure that non-null or non-empty values are provided to parameters; however, the error messages returned to users are not consistent and not necessarily as clear as they should be. Below are some command invocations along with the errors that are produced in PowerShell Core 6.2.1 today. Note that these are just the error message -- the command name, position and other details have been stripped.\r\n\r\n|Command|Error Message|\r\n|--|--|\r\n|`Test-Mandatory -String $null`|`Cannot bind argument to parameter 'String' because it is an empty string.`|\r\n|`Test-Mandatory -Object $null`|`Cannot bind argument to parameter 'Object' because it is null.`|\r\n|`Test-Validator -String $null`|`Cannot validate argument on parameter 'String'. The argument is null or empty. Provide an argument that is not null or empty, and then try the command again.`|\r\n|`Test-Validator -Object $null`|`Cannot validate argument on parameter 'Object'. The argument is null. Provide a valid value for the argument, and then try running the command again.`|\r\n\r\nThe message that each of these errors tries to convey to the caller is that they provided an invalid value into a parameter, and sometimes they suggest what should be done while encouraging them to try again. Unfortunately, the error message that appears does not actually convey that message very well.\r\n\r\n`Cannot bind argument to parameter...`\r\n\r\nWhile it is true that the parameter binder was unable to bind the value provided to a certain parameter, the end user doesn't need to know those technical details.\r\n\r\n`Cannot validate argument on parameter...`\r\n\r\nThese error messages are misleading, and could sound like PowerShell was unable to perform the validation on a parameter value.\r\n\r\n`...because it is an empty string.`\r\n\r\nThis does not properly cover the case where `$null` is accidentally passed into a mandatory string parameter, which is not helpful to end users.\r\n\r\nAlso, the `Mandatory` error messages do not suggest the user try again, but the `Validator` error messages do.\r\n\r\nIn all cases, these error messages should be clear, consistent, and since PowerShell is used interactively in a shell, directed towards the end user so that they can more easily correct the problem.\r\n\r\nI propose that we change the error messages for the commands shown above to the messages shown below instead.\r\n\r\n|Command|Error Message|\r\n|--|--|\r\n|`Test-Mandatory -String $null`|`The null or empty value provided for the 'String' parameter is invalid. Try running the command again with a value for the 'String' parameter that is not null or empty.`|\r\n|`Test-Mandatory -Object $null`|`The null value provided for the 'Object' parameter is invalid. Try running the command again with a value for the 'Object' parameter that is not null.`|\r\n|`Test-Validator -String $null`|`The null or empty value provided for the 'String' parameter is invalid. Try running the command again with a value for the 'String' parameter that is not null or empty.`|\r\n|`Test-Validator -Object $null`|`The null value provided for the 'Object' parameter is invalid. Try running the command again with a value for the 'Object' parameter that is not null.`|\r\n\r\nThese messages are targeted towards the end user who is invoking the command, consistent regardless of whether the parameter is `Mandatory` or using a `ValidateNotNull` or `ValidateNotNullOrEmpty` validator, they clearly identify the problem, and they tell the user what to do to fix the problem.\r\n\r\nBetter, yes?\r\n\r\n# Environment data\r\n\r\n```none\r\nName Value\r\n---- -----\r\nPSVersion 6.2.1\r\nPSEdition Core\r\nGitCommitId 6.2.1\r\nOS Microsoft Windows 10.0.17763\r\nPlatform Win32NT\r\nPSCompatibleVersions {1.0, 2.0, 3.0, 4.0…}\r\nPSRemotingProtocolVersion 2.3\r\nSerializationVersion 1.1.0.1\r\nWSManStackVersion 3.0\r\n```\r\n","author":{"url":"https://github.com/KirkMunro","@type":"Person","name":"KirkMunro"},"datePublished":"2019-07-03T16:36:38Z","url":"https://github.com/PowerShell/PowerShell/issues/10056"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:a09aab45-e13b-76c8-d4d0-1d279183c940 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | C8D2:25F138:169B50:1EA310:6AFD4E57 |
| html-safe-nonce | 95e865a79c1b28eb15b9dcf88733f4c1d1edd287a21b5b97cb1114d9f40fc6e8 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDOEQyOjI1RjEzODoxNjlCNTA6MUVBMzEwOjZBRkQ0RTU3IiwidmlzaXRvcl9pZCI6IjM0MTMzNTUwOTM0MTAyNzA4MDciLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 09c701b679f031332076dedb9e45b9626c8f2736a469e265aa70a7ffccd3a733 |
| hovercard-subject-tag | issue:463849976 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/PowerShell/PowerShell/10056/issue_layout |
| twitter:image | https://opengraph.githubassets.com/300b888156bcdef91665e5f8b85315b5c250d52707b95a0399e2c0e47ae603f8/PowerShell/PowerShell/issues/10056 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/300b888156bcdef91665e5f8b85315b5c250d52707b95a0399e2c0e47ae603f8/PowerShell/PowerShell/issues/10056 |
| og:image:alt | When a user provides an invalid value to a parameter, the error message that they receive should be crystal clear. Today, that is not the case. For example, consider these empty command definitions... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | KirkMunro |
| hostname | github.com |
| expected-hostname | github.com |
| None | 66653c2e55a6fff2930be1bdf07ee4f8aa137e3956d056c822563be6f878755e |
| turbo-cache-control | no-preview |
| go-import | github.com/PowerShell/PowerShell git https://github.com/PowerShell/PowerShell.git |
| octolytics-dimension-user_id | 11524380 |
| octolytics-dimension-user_login | PowerShell |
| octolytics-dimension-repository_id | 49609581 |
| octolytics-dimension-repository_nwo | PowerShell/PowerShell |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 49609581 |
| octolytics-dimension-repository_network_root_nwo | PowerShell/PowerShell |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | b6f01f7cb9f35f8c09949773241a3d49dd04b340 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width