**ANALYSIS SKILL** — Troubleshoot Azure Local deployment, registration, and update failures: collect logs, use the diagnostic support tools, and open support. WHEN: "troubleshoot Azure Local", "Azure Local deployment failed", "collect logs Azure Local", "Azure Local registration issue", "deployment validation failed", "diagnostic support tool", "update failed Azure Local", "Configurator app issue". USE FOR: diagnosing Azure Local infrastructure failures. DO NOT USE FOR: tenant app/Kubernetes debugging (use azure-diagnostics).
**ANALYSIS SKILL** — Troubleshoot Azure Local deployment, registration, and update failures: collect logs, use the diagnostic support tools, and open support. WHEN: "troubleshoot Azure Local", "Azure Local deployment failed", "collect logs Azure Local", "Azure Local registration issue", "deployment validation failed", "diagnostic support tool", "update failed Azure Local", "Configurator app issue". USE FOR: diagnosing Azure Local infrastructure failures. DO NOT USE FOR: tenant app/Kubernetes debugging (use azure-diagnostics).
compatibility
Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool.
This skill is grounded in the vendored Microsoft docs under docs/upstream/azure-local/. Prefer those files over prior knowledge, cite the file you used, and treat Microsoft Learn as canonical when the weekly mirror lags.
Triggers
Activate this skill when the user wants to:
Diagnose a deployment, registration, or update that did not complete
Collect logs or engage Microsoft support with the right diagnostics
Run the diagnostic support tools
Rules
Prefer the vendored docs under docs/upstream/azure-local/; cite the exact file used.
Scope the failure class (deployment validation vs registration vs update) before acting.
Collect logs and run the diagnostic support tools before opening a support case.
Microsoft Learn / discovered governance wins over the mirror on any conflict.
Steps
Reproduce/scope the failure (deployment validation vs registration vs update).
Collect logs and run the diagnostic support tools.
Apply targeted fixes from the matching troubleshooting doc.
Open support with collected diagnostics if unresolved.
Workload VM / AVD symptoms
For workload (Arc VM, SQL, AVD) failures rather than infrastructure failures, also see
azlocal-vm-management and azlocal-workloads. Common symptoms observed in practice:
Symptom
Likely cause
Fix
VM shows 0 CPU / 0 MB, won't boot, guest agent never installs
Sized with an Azure SKU name / Default, or --hardware-profile without vm-size="Custom"
Recreate with hardwareProfile.vmSize:'Custom' + processors + memoryMB (Bicep). A post-create resize cannot revive a 0/0 VM.
guestAgentInstallStatus.status is null on a healthy VM
Expected on Azure Local — that field is unreliable
Judge health by instanceView.vmAgent.statuses[0].displayStatus + Arc machine status=Connected and non-null agentVersion.
In-guest run-command returns Unknown / empty; az stack-hci-vm run-command not found
HybridCompute runCommands doesn't dispatch reliably on Azure Local; that CLI verb doesn't exist
Use an Arc machine extension (JsonADDomainExtension, CustomScriptExtension) instead.
az stack-hci-vm show --query returns empty
CLI quirk for these resource types
Read via az rest GET .../virtualMachineInstances/default?api-version=2024-01-01.
AVD registration token comes back empty
Older desktopvirtualization CLI ext / GET ?$expand=registrationInfo
Use REST POST .../hostPools/<hp>/retrieveRegistrationToken?api-version=2025-10-10.
Marketplace VM image create fails
Microsoft.EdgeMarketplace RP not registered
Register the provider, then recreate the image; confirm Succeeded before VM create.
AVD session host stuck Unavailable
Agent/boot-loader not installed, not AD-joined, or no outbound 443 to the AVD broker / IMDS
Verify domain join + Connected Machine agent, install the AVD agent via extension, and confirm egress.
