{"id":89,"date":"2023-06-16T16:19:50","date_gmt":"2023-06-16T23:19:50","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/?p=89"},"modified":"2023-06-16T16:19:50","modified_gmt":"2023-06-16T23:19:50","slug":"how-to-determine-if-your-runcommand-script-failed","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/how-to-determine-if-your-runcommand-script-failed\/","title":{"rendered":"How to determine if your Runcommand script failed"},"content":{"rendered":"

Today, we’re going to cover what can be a maddening issue in just determining whether your script failed.<\/p>\n

Let’s start with a very simple operation. Open a Powershell window and run the following:<\/p>\n

PS C:\\> this is an error\r\n\r\nthis: The term 'this' is not recognized as a name of a cmdlet, function, script file, or executable program.\r\nCheck the spelling of the name, or if a path was included, verify that the path is correct and try again.<\/pre>\n
This shouldn’t be rocket science here. It’s very clear that “this is an error” is, in fact, an error. So, with this universal fact determined, let’s run it on an Azure VM.<\/p>\n
Set-AzVmRunCommand -ResourceGroupName $rg -VMName $vm -Location $loc -RunCommandName \"MyRuncommand\" -SourceScript \"this is an error\"<\/pre>\n
And now let’s see the result.<\/p>\n
Get-AzVMRunCommand -ResourceGroupName $rg -VMName $vm -RunCommandName \"MyRuncommand\" -Expand \"instanceView\" | select-object *\r\n\r\nAsyncExecution : False\r\nErrorBlobUri :\r\nId : {removed}\r\nInstanceViewEndTime : 16.06.2023 22:55:11\r\nInstanceViewError : this : The term 'this' is not recognized as the name of a cmdlet, function, script file, or operable program. Check<\/strong>\r\nthe spelling of the name, or if a path was included, verify that the path is correct and try again.<\/strong>\r\nAt C:\\Packages\\Plugins\\Microsoft.CPlat.Core.RunCommandHandlerWindows\\2.0.5\\Downloads\\Script_MyRuncommand_0.ps1:1 char:1<\/strong>\r\n+ this is an error<\/strong>\r\n+ ~~~~<\/strong>\r\n+ CategoryInfo : ObjectNotFound: (this:String) [], CommandNotFoundException<\/strong>\r\n+ FullyQualifiedErrorId : CommandNotFoundException<\/strong>\r\n\r\nInstanceViewExecutionMessage :\r\nInstanceViewExecutionState : Succeeded<\/strong>\r\nInstanceViewExitCode : 0<\/strong>\r\nInstanceViewOutput :\r\nInstanceViewStartTime : 16.06.2023 22:55:08\r\nInstanceViewStatuses :\r\nLocation : westus2\r\nName : MyRuncommand\r\nOutputBlobUri :\r\nParameter :\r\nProtectedParameter :\r\nProvisioningState : Succeeded\r\nRunAsPassword :\r\nRunAsUser :\r\nSourceCommandId :\r\nSourceScript : this is an error\r\nSourceScriptUri :\r\nTag : Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.ResourceTags\r\nTimeoutInSecond : 0\r\nType : Microsoft.Compute\/virtualMachines\/runCommands<\/pre>\n
Note that you need to pass in -expand “instanceView” to see the actual error. Without this, you’ll receive the following.<\/p>\n
AsyncExecution : False\r\nErrorBlobUri :\r\nId : {removed}\r\nInstanceViewEndTime :\r\nInstanceViewError :<\/strong>\r\nInstanceViewExecutionMessage :\r\nInstanceViewExecutionState :\r\nInstanceViewExitCode :<\/strong>\r\nInstanceViewOutput :\r\nInstanceViewStartTime :\r\nInstanceViewStatuses :\r\nLocation : westus2\r\nName : MyRuncommand\r\nOutputBlobUri :\r\nParameter :\r\nProtectedParameter :\r\nProvisioningState : Succeeded\r\nRunAsPassword :\r\nRunAsUser :\r\nSourceCommandId :\r\nSourceScript : this is an error\r\nSourceScriptUri :\r\nTag : Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.ResourceTags\r\nTimeoutInSecond : 0\r\nType : Microsoft.Compute\/virtualMachines\/runCommands<\/pre>\n
This leads one to believe everything worked, when it didnt’t.<\/p>\n
So, the first lesson of Runcommand error viewing is: always check the instanceView<\/strong>!<\/p>\n
Of course, most of us are keen enough to not write scripts like this. Instead, we’re probably going to detect problems and throw, so let’s try that.<\/p>\n
Set-AzVmRunCommand -ResourceGroupName $rg -VMName $vm -Location $loc -RunCommandName \"Myruncommand\" -SourceScript \"throw 'blah'\"\r\n\r\nGet-AzVMRunCommand -ResourceGroupName $rg -VMName $vm -RunCommandName \"MyRuncommand\" -Expand \"instanceView\" | select-object *\r\n\r\nAsyncExecution : False\r\nErrorBlobUri :\r\nId : {removed}\r\nInstanceViewEndTime : 16.06.2023 23:02:52\r\nInstanceViewError : blah<\/strong>\r\nAt C:\\Packages\\Plugins\\Microsoft.CPlat.Core.RunCommandHandlerWindows\\2.0.5\\Downloads\\Script_MyRuncommand_1.ps1:1 char:1<\/strong>\r\n+ throw 'blah'<\/strong>\r\n+ ~~~~~~~~~~~~<\/strong>\r\n+ CategoryInfo : OperationStopped: (blah:String) [], RuntimeException<\/strong>\r\n+ FullyQualifiedErrorId : blah<\/strong>\r\n\r\nInstanceViewExecutionMessage :\r\nInstanceViewExecutionState : Failed<\/strong>\r\nInstanceViewExitCode : 1<\/strong>\r\nInstanceViewOutput :\r\nInstanceViewStartTime : 16.06.2023 23:02:51\r\nInstanceViewStatuses :\r\nLocation : westus2\r\nName : MyRuncommand\r\nOutputBlobUri :\r\nParameter :\r\nProtectedParameter :\r\nProvisioningState : Succeeded\r\nRunAsPassword :\r\nRunAsUser :\r\nSourceCommandId :\r\nSourceScript : throw 'blah'\r\nSourceScriptUri :\r\nTag : Microsoft.Azure.PowerShell.Cmdlets.Compute.Models.Api20210701.ResourceTags\r\nTimeoutInSecond : 0\r\nType : Microsoft.Compute\/virtualMachines\/runCommands<\/pre>\n
So, again we can see the error in the instanceView, but something else has changed. the instanceViewExitCode is now 1 and instanceViewExecutionState is failed! But in the previous case it was 0 and success, even though we still had an error. The issue is in terminating vs non-terminating errors in Powershell<\/a>.<\/p>\n
The following are other options to return an error.<\/p>\n
Set-AzVmRunCommand -ResourceGroupName $rg -VMName $vm -Location $loc -RunCommandName \"Myruncommand\" -SourceScript \"write-error 'blah' -ErrorAction Stop\"<\/pre>\n
This results in the following.<\/p>\n
InstanceViewError : C:\\Packages\\Plugins\\Microsoft.CPlat.Core.RunCommandHandlerWindows\\2.0.5\\Downloads\\Script_MyRuncommand_2.ps1 : blah\r\nAt C:\\Packages\\Plugins\\Microsoft.CPlat.Core.RunCommandHandlerWindows\\2.0.5\\Downloads\\Script_MyRuncommand_2.ps1:1 char:1\r\n+ write-error 'blah' -ErrorAction Stop\r\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n+ CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException\r\n+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Script_MyRuncommand_2.ps1\r\n\r\nInstanceViewExecutionMessage :\r\nInstanceViewExecutionState : Failed\r\nInstanceViewExitCode : 1<\/pre>\n
You can also change the exit code with<\/p>\n
Set-AzVmRunCommand -ResourceGroupName $rg -VMName $vm -Location $loc -RunCommandName \"Myruncommand\" -SourceScript \"exit 42\"<\/pre>\n
Note that in this case there is no value for Error.<\/p>\n
InstanceViewError :\r\nInstanceViewExecutionMessage :\r\nInstanceViewExecutionState : Failed\r\nInstanceViewExitCode : 42<\/pre>\n
So, I hope this provides some guidance on checking for RunCommand failures in your automation.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
Today, we’re going to cover what can be a maddening issue in just determining whether your script failed. Let’s start with a very simple operation. Open a Powershell window and run the following: PS C:\\> this is an error this: The term ‘this’ is not recognized as a name of a cmdlet, function, script file, […]<\/p>\n","protected":false},"author":103696,"featured_media":90,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[6],"tags":[5,11,9,10],"class_list":["post-89","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-runcommand","tag-azure","tag-failures","tag-runcommand","tag-vmextensions"],"acf":[],"blog_post_summary":"
Today, we’re going to cover what can be a maddening issue in just determining whether your script failed. Let’s start with a very simple operation. Open a Powershell window and run the following: PS C:\\> this is an error this: The term ‘this’ is not recognized as a name of a cmdlet, function, script file, […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/posts\/89","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/users\/103696"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/comments?post=89"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/posts\/89\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/media\/90"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/media?parent=89"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/categories?post=89"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-vm-runtime\/wp-json\/wp\/v2\/tags?post=89"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}