VMExtensionNotFound
Azure returns `VMExtensionNotFound` when a VM operation references an extension resource name that does not exist on the target VM.
Last reviewed: February 7, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does VM Extension Not Found Mean?
Extension update, remove, or query workflows fail for the target VM, leaving configuration drift unresolved until extension identity is corrected.
Common Causes
- -Deployment references an extension name that is not installed on the VM.
- -Automation targets the wrong VM or scale-set instance for extension operations.
- -Extension was removed manually or by another pipeline between plan and apply steps.
- -Publisher/type/version mismatch caused previous extension install to fail or roll back.
How to Fix VM Extension Not Found
- 1List extensions on the target VM and use the exact extension resource name returned by Azure.
- 2Validate VM resource ID and scope before invoking extension update/remove calls.
- 3Install or re-install the extension with correct publisher, type, and handler version when missing.
- 4Rerun operation and confirm extension provisioning state transitions to
Succeeded.
Step-by-Step Diagnosis for VM Extension Not Found
- 1Inspect ARM deployment or API failure details to identify the exact extension name Azure cannot find.
- 2Compare desired extension name in IaC/state files against
az vm extension listoutput. - 3Review extension instance view and agent logs for prior failed installs that left partial state.
- 4Audit parallel automation jobs for remove/redeploy actions touching the same extension.
Extension Identity and Handler Validation
- -Verify extension resource naming and handler metadata (example: template calls
IaaSAntimalwarewhile VM hasMicrosoftMonitoringAgent). - -Inspect publisher/type/version compatibility (example: unsupported handler version requested for the VM OS image).
VM Scope and Orchestration Checks
- -Audit VM or VMSS instance targeting in automation (example: extension update sent to old instance ID after scale set replacement).
- -Trace concurrent deployment jobs that may remove extensions mid-rollout (example: security baseline pipeline deletes custom extension before app pipeline update).
Seen in Production
Hardening pipeline removed extension expected by app deployment
Frequency: common
Example: App rollout tries to update a monitoring extension that was deleted earlier.
Fix: Reinstall extension from baseline and enforce pipeline ownership boundaries.
Scale set rolling upgrade replaced instance targeted by extension job
Frequency: rare
Example: Job references old instance extension path and receives not-found.
Fix: Refresh instance identity before extension operations in each rollout step.
Debugging Tools
- -az vm extension list / show
- -VM extension instance view and provisioning state
- -ARM deployment operation logs
- -Guest/agent extension logs on VM
How to Verify the Fix
- -Run extension list/get and confirm the expected extension resource now exists on the target VM.
- -Re-execute the failing extension action and verify no
VMExtensionNotFoundresponse is returned. - -Confirm dependent provisioning steps complete successfully after extension state is corrected.
How to Prevent Recurrence
- -Manage VM extensions declaratively with a single source of truth and drift detection.
- -Serialize extension lifecycle actions to avoid concurrent remove/update conflicts.
- -Pin tested extension publisher/type/version combinations per VM image baseline.
Pro Tip
- -capture and diff
az vm extension list --query "[].{name:name,publisher:publisher,type:typeHandlerVersion}"in CI to detect unexpected extension drift before rollout.
Official References
Provider Context
This guidance is specific to Azure services. Always validate implementation details against official provider documentation before deploying to production.