Azure VM Extension 'ProvisioningState' shows failed — fix it fast

Quick answer

If you're comfortable with Azure CLI and have Contributor access, run az vm extension list --resource-group myRG --vm-name myVM --query "[?provisioningState=='Failed']" to find the failing extension, then delete it with az vm extension delete and reinstall. But that's often not enough — you need to check the VM agent first.

Why this happens

Azure VM extensions (like Custom Script Extension, Dependency Agent, or Backup Extension) rely on the Azure VM Agent (also called waagent on Linux) to run. When the agent can't talk back to Azure, or when the extension script times out, you get a ProvisioningState: Failed in the portal or CLI. I've seen this happen most often when:

• The VM has a Network Security Group (NSG) that blocks outbound traffic to 168.63.129.16 (Azure's metadata endpoint).
• The VM agent is stuck or outdated — especially on Windows Server 2016 or Ubuntu 18.04 LTS.
• The VM has a firewall inside the OS (like iptables or Windows Firewall) blocking extension scripts.
• The extension itself has a wrong parameter — like a bad script URL or a missing storage account key.

The fixes below start with the most common cause (network) and go deeper from there.

Fix steps — in order

Step 1: Check the VM agent is running

1. Connect to the VM via SSH (Linux) or RDP (Windows).
2. On Windows: Open Task Manager > Services tab. Look for WindowsAzureGuestAgent. It should say Running. If it's stopped, right-click and start it.
3. On Linux: Run systemctl status waagent. You want to see active (running). If not, run sudo systemctl restart waagent. After restarting, wait 30 seconds, then check again.

Step 2: Test network connectivity to Azure metadata endpoint

This is the big one. Azure extensions need to reach 168.63.129.16 on TCP port 80. If that's blocked, the extension will fail every time.

1. From the VM, run a quick test:
   

   # Linux
   telnet 168.63.129.16 80
   
   # Windows (PowerShell)
   Test-NetConnection 168.63.129.16 -Port 80

2. If the connection fails (or times out), check your NSG rules: go to the VM's network interface in Azure portal > NSG > Inbound/Outbound rules. Make sure there's an Allow rule for Any protocol to 168.63.129.16 on port 80. If you have a deny-all rule, add this one with a higher priority.
3. Also check Azure Firewall or any custom routing (like UDRs) that might force traffic away from the metadata endpoint.

Step 3: Restart the VM agent and wait

Sometimes the agent is just in a bad state. Restart it from the VM's OS:

• Windows: Open Command Prompt as admin, run net stop WindowsAzureGuestAgent then net start WindowsAzureGuestAgent. Wait 2 minutes.
• Linux: Run sudo systemctl restart waagent then sudo systemctl status waagent.

After restarting, check the extension status in Azure portal again. It might take 5–10 minutes to update.

Step 4: Delete and reinstall the failed extension

If the agent is healthy and network is open, just delete the bad extension and try again.

1. Run this Azure CLI command (replace your resource group and VM name):
   

   az vm extension list --resource-group myRG --vm-name myVM --query "[?provisioningState=='Failed'].{Name:name}" --output tsv

2. Take the extension name from the output, then delete it:
   

   az vm extension delete --resource-group myRG --vm-name myVM --name ExtensionName

3. Now reinstall the extension through the portal or CLI. For example, to reinstall the Custom Script Extension:
   

   az vm extension set --resource-group myRG --vm-name myVM --name CustomScriptExtension --publisher Microsoft.Compute --settings '{"fileUris": ["https://myblob.blob.core.windows.net/scripts/myscript.ps1"]}' --protected-settings '{"commandToExecute": "powershell -ExecutionPolicy Unrestricted -File myscript.ps1"}'

What to try if the main fixes don't work

Alternative 1: Update the VM agent

Old agents are buggy. On Windows, download the latest Azure VM Agent installer and run it. On Linux, run sudo apt update && sudo apt install walinuxagent -y (for Debian/Ubuntu) or sudo yum update waagent -y (for RHEL/CentOS). Reboot after updating.

Alternative 2: Check the extension logs

Extension logs tell you the real error. On Windows, look in C:\Packages\Plugins\*\Status\0.status. On Linux, look in /var/lib/waagent/ for a folder named after the extension. Inside, there's a status/0.status file. Open it — it's JSON. Look for message or code fields. Common errors: commandToExecute script failed, wrong file URL, or script timeout.

Alternative 3: Reinstall the VM agent

This is last resort but works when the agent is corrupted. On Windows, download the agent installer from the same link above, uninstall the old one from Control Panel, then install fresh. On Linux, run sudo apt purge walinuxagent && sudo apt install walinuxagent -y (or yum equivalent). Then reboot the VM.

How to prevent this from happening again

Set up a network check before deploying new extensions. Use Azure Policy or a simple script to confirm the NSG allows outbound to 168.63.129.16. Also, keep VM agents updated automatically. On Windows, enable automatic updates for the Guest Agent. On Linux, set up a cron job to run apt update && apt upgrade walinuxagent weekly. Finally, always test extension scripts on a test VM first. I've seen too many production fails because of a typo in the script URL.

Real-world scenario: A customer had a Linux VM running an old Backup Extension. The NSG had a deny-all outbound rule. Every backup failed. After adding an allow rule for 168.63.129.16 and updating the agent, backups started working in 10 minutes.