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(
        [Parameter(Mandatory, ParameterSetName='StringTest')]
        [string]
        $String,

        [Parameter(Mandatory, ParameterSetName='ObjectTest')]
        [object]
        $Object
    )
}

function Test-Validator {
    param(
        [ValidateNotNullOrEmpty()]
        [string]
        $String,

        [ValidateNotNull()]
        [object]
        $Object
    )
}

When 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.

The 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.

Cannot bind argument to parameter...

While 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.

Cannot validate argument on parameter...

These error messages are misleading, and could sound like PowerShell was unable to perform the validation on a parameter value.

...because it is an empty string.

This does not properly cover the case where $null is accidentally passed into a mandatory string parameter, which is not helpful to end users.

Also, the Mandatory error messages do not suggest the user try again, but the Validator error messages do.

In 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.

I propose that we change the error messages for the commands shown above to the messages shown below instead.

These 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.

Better, yes?

Environment data

Name                           Value
----                           -----
PSVersion                      6.2.1
PSEdition                      Core
GitCommitId                    6.2.1
OS                             Microsoft Windows 10.0.17763
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0