How to find failed PowerShell scripts in Microsoft Intune

Before you start

Use an Intune Administrator, or an account with an Intune role that can read configuration and devices, such as Read Only Operator. The tenant needs an active Intune licence. The PowerShell example requests DeviceManagementScripts.Read.All for the scripts and DeviceManagementManagedDevices.Read.All for the device names; your organisation may require administrator consent.

The guide covers platform scripts for Windows. Remediations and macOS shell scripts keep their run states in lists of their own. The beta API changes more often than version 1.0, Microsoft says. The examples read and export and change nothing.

Option 1

Find failed PowerShell scripts with PowerShell

Install the modules once, then connect, read each platform script's failed runs and export them.

# Install once, if the modules are not already installed.
Install-Module Microsoft.Graph.Authentication,
    Microsoft.Graph.Beta.DeviceManagement -Scope CurrentUser

$ErrorActionPreference = 'Stop'
$scopes = 'DeviceManagementScripts.Read.All', 'DeviceManagementManagedDevices.Read.All'
Connect-MgGraph -Scopes $scopes -NoWelcome
try {
    $scripts = @(Get-MgBetaDeviceManagementScript -All -Property 'id', 'displayName')
    $report = foreach ($script in $scripts) {
        $request = @{
            DeviceManagementScriptId = $script.Id
            Filter = "runState eq 'fail'"
            ExpandProperty = 'managedDevice'
            All = $true
        }
        foreach ($state in Get-MgBetaDeviceManagementScriptDeviceRunState @request) {
            $message = $state.ErrorDescription
            if (-not $message) { $message = $state.ResultMessage }
            [pscustomobject]@{
                Script = $script.DisplayName
                Device = $state.ManagedDevice.DeviceName
                User = $state.ManagedDevice.UserPrincipalName
                Error = $message
                ErrorCode = $state.ErrorCode
                LastUpdate = $state.LastStateUpdateDateTime
            }
        }
    }
    $report = @($report | Sort-Object Script, Device)
    if ($report.Count -eq 0) {
        Write-Output "No device reports a failed run of the $($scripts.Count) scripts."
    } else {
        $report | Export-Csv -Path './failed-scripts.csv' -NoTypeInformation -Encoding utf8
        Write-Output "$($report.Count) failed script runs written to failed-scripts.csv."
    }
} finally {
    Disconnect-MgGraph | Out-Null
}

The CSV has 1 row for each script and device where the last run failed, with the error the device reported and when it last reported, in UTC. The filter runs in Microsoft Graph, so only the failed runs come back. To see every outcome, remove the Filter line and add RunState = $state.RunState to the row; the states are success, fail, scriptError, pending, notApplicable and unknown.

Option 2

Check a script's device status in the admin centre

1. Sign in to the Microsoft Intune admin centre for the correct tenant.
2. Go to Devices > Scripts and remediations and select the Platform scripts tab.
3. Select the script, then under Monitor select Device status.
4. Read the status of each device, and export it if you want to keep it. Leave the script's settings and assignments alone.

This suits checking 1 script after a change. Every script means opening each in turn, so for the whole tenant use PowerShell or a report.

Common questions

Why doesn't a failed script run again?

Microsoft says a failed script is retried at the next 3 check-ins of the Intune management extension. After that it doesn't run again until the script or the policy changes. Fix the cause, then change the script or its assignment so devices pick it up.

Why does a script fail on some devices and not others?

Check what differs. Microsoft says scripts time out after 30 minutes, fail to run when a device's clock is months out, and run in a 32-bit PowerShell host unless Run script in 64-bit PowerShell host is set to Yes.

Does this include remediations and macOS scripts?

No. In Microsoft Graph, remediations and macOS shell scripts have device run states of their own, so the script above leaves them out. For other things that fail on devices, see how to find app install failures in Microsoft Intune.