Troubleshoot Azure VM extension failures by checking agent health, extension status, networking, permissions and guest operating system conditions.
Identify the exact extension and error code, confirm the VM agent is healthy, then check network access to Azure endpoints and guest-side conditions.
Remove a failed extension before reapplying rather than reapplying over it — a stuck extension in a Failed state can block redeployment with a stale-state error.
Capture the extension name, version, provisioning state and exact error returned by Azure.
Identify the extension and its exact error
Pull the full extension status rather than relying on the portal's summary, which often truncates the actual error message:
Get-AzVMExtension -ResourceGroupName "RG" -VMName "VMName" | Select-Object Name, ProvisioningState, StatusCode, StatusMessageNote the extension's exact name and version — some extensions (like the Custom Script Extension) fail in ways that are entirely about the script's own exit code, not the extension framework itself, so the first question is always "did the extension framework fail, or did the payload it ran fail?"
Check the Azure VM Agent
Every extension depends on the Azure VM Agent (waagent on Linux, WindowsAzureGuestAgent on Windows) being installed, running, and able to reach Azure's extension endpoints. On Windows, check via Run Command since RDP may not be available if the extension issue is network-related:
Invoke-AzVMRunCommand -ResourceGroupName "RG" -VMName "VMName" -CommandId 'RunPowerShellScript' -ScriptString "Get-Service WindowsAzureGuestAgent"An agent that's present but outdated is a common, easy-to-miss cause — some extension versions require a minimum agent version and fail with a generic error rather than an explicit "agent too old" message.
Check guest-side resource conditions
Confirm the VM has free disk space on the system volume — extensions download and stage their payload locally, and a full disk causes extension installation to fail with an error that rarely mentions storage directly. Also check whether third-party antivirus or endpoint protection is blocking the extension's process or file writes; this is a frequent, easy-to-overlook cause on hardened images.
Check network access to required Azure endpoints
The guest agent needs outbound HTTPS access to the Azure fabric (typically via the well-known link-local address 168.63.129.16) to receive extension configuration and report status. If the VM is in a locked-down subnet with a restrictive NSG or forced-tunneled through an NVA/firewall without the right exceptions, extensions will consistently time out. Confirm the NSG explicitly allows outbound access to Azure's platform endpoints and that any custom route table doesn't blackhole this traffic.
Review extension handler logs inside the guest
On Windows, extension handler logs live under C:\WindowsAzure\Logs\Plugins\<ExtensionName>\<Version>. On Linux, under /var/log/azure/<ExtensionName>. Pull these via Run Command if you can't RDP/SSH in directly, and correlate the timestamp with the deployment time shown in the Azure activity log — this tells you whether the extension actually started executing (a payload-side failure) or never got that far (an agent/network-side failure).
Remove before retrying, don't reapply over a failed state
An extension stuck in a Failed provisioning state can block a straightforward reapply with a stale-state error. Remove it explicitly first:
Remove-AzVMExtension -ResourceGroupName "RG" -VMName "VMName" -Name "ExtensionName"Then reapply after confirming the underlying cause is fixed, and check ProvisioningState again — a successful reapply should show Succeeded, not just the absence of an immediate error in the deployment output.