workflows/troubleshooting/troubleshooting.md
Troubleshooting Azure Local
Use this workflow for Azure Local deployment failures, Arc registration/connectivity issues, Arc resource bridge/custom location problems, Azure Local VM or AKS Arc failures, SDN issues, update/upgrade failures, and evidence collection.
Triage sequence
- Classify the failure - Deployment, Arc registration, Arc gateway/private endpoint, Arc resource bridge, custom location, VM management, AKS on Azure Local, SDN, update/upgrade, monitoring, or workload.
- Collect context - Subscription, resource group, Azure Local instance, version, custom location, resource bridge name, affected workload, connectivity model, recent changes, and exact error.
- Check Azure control plane - Use Azure Resource Graph, resource health, activity logs, and extension/resource provisioning states.
- Check local prerequisites only when needed - Some issues require direct access to an Azure Local machine. Use documented local commands only after confirming access and scope.
- Load scenario docs - Use docs-map to fetch the relevant troubleshooting article for the user's version.
- Prefer reversible remediation - Retry, refresh status, fix permissions/connectivity, restore configuration, or complete documented repair steps before deletion/recreation.
- Validate and document - Confirm resource state, Arc connectivity, workload health, and monitoring after remediation.
Scenario routing
| Symptom | First checks | | --- | --- | | Deployment failed | Deployment operation details, prerequisites, topology, AD prep, Arc registration, permissions, portal/ARM errors | | Arc registration failed | Network/proxy/firewall, Arc gateway/private endpoint, subscription permissions, Connected Machine agent state | | Arc resource bridge unhealthy | Resource bridge resource state, VM state on local cluster, custom location, extension status, logs | | Custom location unavailable | Resource bridge health, custom location resource state, namespace/extension mapping, RBAC | | Azure Local VM create/update/delete failed | VM management extension, custom location, image/storage/logical network/NIC dependencies, IPv4/IP pool capacity | | AKS on Azure Local failed | Azure Local health, Arc bridge/custom location, logical network/IP capacity, AKS Arc docs, cluster/node pool status | | SDN issue | Network Controller, certificates, NSGs, load balancer, gateway, datacenter firewall, SDN logs | | Update failed | Update phase, health checks, unsupported update path, solution extension content, offline import status | | Upgrade failed | Upgrade readiness validation, post-upgrade steps, Network ATC, stretched cluster constraints |
Evidence checklist
- Exact error text and operation ID/correlation ID.
- Azure resource IDs for Azure Local, Arc bridge, custom location, VM/AKS/SDN resources.
- Deployment/update/upgrade phase.
- Recent activity log entries.
- Extension provisioning states.
- Connectivity/proxy/private endpoint/Arc gateway configuration.
- Local logs only when Microsoft Learn requires them for the scenario.
Critical safety rules
- Do not delete Arc resource bridge or custom location as a generic fix.
- Do not remove workload resources before confirming dependencies and recovery impact.
- Do not run unsupported update or upgrade repair paths.
- Ask before any remediation that can reboot hosts, interrupt storage/networking, delete resources, or break workload access.