What is the proper way of performing error handling in scripting?

[plamber]

When writing scripts I find it very difficult to properly manage error handling. Proper error handling is key to ensure you can perform repetitive tasks always in the same way. I

Lets take this simple example to see what I mean: Creating a M365 Group in PowerShell.

try {
    $group = m365 aad o365group add --displayName "Contoso Group" `
                                --description "." --mailNickname "demoGroup" `
                                -o "json" | convertfrom-json
}
catch {
    Write-Host "Exception"
}

If you run the script above twice it is going to fail. In the second run you get back this cryptic error message in the output window.

I am not sure if this is a bug of that specific command or if all commands behave like this.

It is challenging for me to do proper error handling. How should I retrieve what went wrong and adapt in my script?
The try catch block is not considered at all. This is ok but then we might require some other way to report errors.

You could for example verifying the output of the variable and put it in an if statement.

if ([String]::IsNullOrWhiteSpace($group.id)) {
    Write-Host "Something went wrong during group creation $group"
}

But now comes the next challenge. I do not know what error happened because the error message is not written back in the variable. At least this command does not provide any valuable information. We could take another example to show that it seems to be a general issue.

$membersToAdd = m365 aad user list --displayName $memberDisplayName --properties "id,userprincipalname" --output "json" | convertfrom-json
$membersToAdd | ForEach-Object {
    Write-Host "Adding member to $($_.userPrincipalName) to Group"
    $variable = m365 aad o365group user add --groupId $group.id --userName $_.id -o "json" | convertfrom-json
}

The command above will try to locate users and add them to a Group. If a user is already a member of the group, the $variable is not filled and the error message is written in the shell output.

I do not see any chances to handle this type of error at all.

I am wondering how do you see this. I think it might be an interesting addition to get back an error message json object that returns some basic information from the backend. With this information it might become easier to handle errors.

Cheers

[garrytrinder]

This blog post may help

https://rajbos.github.io/blog/2019/07/12/Azure-CLI-PowerShell

[plamber]

Thank you @garrytrinder. This might be a good starting point.

$logoPath = ".\pnpImage.png"
$memberDisplayName = "A"
$displayName = "Contoso Group"
$mailNickName = "demoGroup5"
$channelNames = @("Public relations", "CLI Project")

Write-Host "Creating the Group '$displayName'..."
$group = $null
$group = m365 aad o365group add --displayName $displayName `
                                --description "." --mailNickname $mailNickName  `
                                -o "json" | convertfrom-json
if ($LastExitCode -eq 1) {
    Write-Error "Error creating storage account"
    return
}

I see two options now. You can run the lastexitcode -eq 1 check or $group -eq $null check.

On the other hand, how do you handle the error message itself? Maybe based on the error message you want to behave in one or another way.

[waldekmastykarz]

In CLI we distinguish between stdout and stderr. All regular output is sent to stdout and errors to stderr. With that, it's correct with what you're seeing that the variable doesn't have the error message on it as that's sent to a different output. What's interesting to find out is how PowerShell handles stderr and how to get to it when calling regular executables.

[plamber]

Found this way to handle stdout and stderr

$allOutput = & m365 aad o365group teamify -o json 2>&1
$stderr = $allOutput | ?{ $_ -is [System.Management.Automation.ErrorRecord] }
$stdout = $allOutput | ?{ $_ -isnot [System.Management.Automation.ErrorRecord] }

I think we should stick with
if ($LastExitCode -eq 1) {
Write-Error "Something went wrong"
return
}

[waldekmastykarz]

Checking the exit code is indeed an easy way to see if the command succeeded or not. If you want to show the actual error, then getting stderr is the way to go.

This would btw be a great addition to our docs 😁

[plamber]

Hi @waldekmastykarz and @garrytrinder ,
I think I found an elegant way to handle Exceptions. Have a look into this code and let me know how we could further improve it.

m365 cli config set --key output --value json

function M365-CLI {
[cmdletbinding()]
param(
    [parameter(Mandatory = $true, ValueFromPipeline = $true)]
    $input,
    [parameter(Mandatory = $false)]
    $convertFromJson = $true
)

    $errorData = $input | ?{ $_.gettype().Name -eq "ErrorRecord" }
    $isError = $errorData.Count -gt 0
    if ($isError) {
        throw $errorData
    }

    if ($convertFromJson) {
        return $input | ConvertFrom-Json
    }
    else {
        return $input
    }
}

try {
    $works = m365 aad user list 2>&1 | M365-CLI
    $withoutConvertFromJson = m365 aad user list 2>&1 | M365-CLI -convertFromJson $false
    $willGetIntoException = m365 aad o365group teamify --groupId "523fe8a2-9f37-47ce-ad89-751c53df93d7" 2>&1 | M365-CLI 
}
catch {
    Write-Host "Exception" -ForegroundColor Red
    Write-Host $_ -ForegroundColor Red
}
```

[waldekmastykarz]

It would be interesting to dig more into PowerShell to see if it supports passing stderr to pipeline. If that's not possible, we could consider introducing a setting that allows you to choose to write error output to stdin to keep things simple in PowerShell. I vaguely recall that we've talked about it in the past.

[waldekmastykarz]

Not sure if you've seen this post https://rajbos.github.io/blog/2019/07/12/Azure-CLI-PowerShell that explains handling errors in Azure CLI in PowerShell, which is similar to our CLI. Not sure if these techniques would be enough or if it would be more reliable still to look at the returned error message.

[waldekmastykarz]

I asked around and it seems like you can only pass stdout to pipeline in PowerShell. That said, what do you think @plamber, shall we introduce a config option that automatically writes all errors to stdout so that you don't need to fiddle with it if you use CLI in PowerShell and which would also simplify error handling?

[plamber]

You know already my answer ;)

[waldekmastykarz]

Let me propose an issue then and we take it from there 👏

[waldekmastykarz]

We've just released support for configuring error output to stdout (#2325) which should simplify handling errors in PowerShell.

[plamber]

Hi @waldekmastykarz and @veronicageek,
find here an example how you can use try catch using the latest version of m365cli and a small helper method I created.

This lets you handle exceptions in a simpler way using the CLI

// this function checks if the CLI input is either an error or not. In case of an error it throws an exception, otherwise it returns a converted object from json
function Get-CLIValue {
[cmdletbinding()]
param(
    [parameter(Mandatory = $true, ValueFromPipeline = $true)]
    $input,
    [parameter(Mandatory = $false)]
    $convertFromJson = $true
)
    if ($convertFromJson) {
      try {
        return $input | ConvertFrom-Json
      }
      catch {
        
      }
    }

    if ($input.StartsWith("Error:")) {
        $errorMessage = $input.Replace("Error: ", "")
        throw $errorMessage
    }

    return $input
}

# configure the CLI to output JSON on each execution
m365 cli config set --key output --value json
m365 cli config set --key errorOutput --value stdout
m365 cli config set --key showHelpOnFailure --value false

try {
   // this command will fail due to missing parameters
   $convertedObject = m365 teams team get | Get-CLIValue 
}
catch  {
    Write-Host $_.Exception.Message -ForegroundColor Red
}

[veronicageek]

Hi @plamber,
I haven't tried the latest version yet and still learning CLI, but I have a few questions 😇

The if ($input.StartsWith("Error:")) is assuming that all the possible errors in CLI for whatever script you're running start with the word "Error". Is this always the case when using CLI? (it isn't in Powershell for example).

Is your first try/catch necessary? Because you're not catching anything.

[plamber]

Hi,
The script assumes that the cli is passing JSON. It will fail if this is not the case. This happens if the cli is returning an error (no json) or some other unexpeted output. This is also the reason of having the first try catch.

Then I am verifying if the outupt string starts with error. This is always returned by the CLI with error message. If this is the case, I manipulate the string to return the plain message and throw it as an exception.

The last part returns all other outputs.

I havent found a better way to distinguish between an expected output (successful JSON response) and the error message.

Hope this helps.

Br

[plamber]

Hi,
the latest version of the CLI allows you to make it even simpler.

m365 cli config set --key output --value json
m365 cli config set --key errorOutput --value stdout
m365 cli config set --key showHelpOnFailure --value false
m365 cli config set --key printErrorsAsPlainText --value false

function Get-CLIValue {
  [cmdletbinding()]
  param(
    [parameter(Mandatory = $true, ValueFromPipeline = $true)]
    $input
  )
    $output = $input | ConvertFrom-Json
    if ($output.error -ne $null) {
    throw $output.error
    }
    return $output
 }

try {
   // this command will fail due to missing parameters
   $convertedObject = m365 teams team get | Get-CLIValue 
}
catch  {
    Write-Host $_.Exception.Message -ForegroundColor Red
}

//cc @veronicageek

Cheers,

[plamber]

@waldekmastykarz : could you mark this as the proper answer for better reference?