Troubleshooting

1. 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.
2. Collect context - Subscription, resource group, Azure Local instance, version, custom location, resource bridge name, affected workload, connectivity model, recent changes, and exact error.
3. Check Azure control plane - Use Azure Resource Graph, resource health, activity logs, and extension/resource provisioning states.
4. 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.
5. Load scenario docs - Use docs-map to fetch the relevant troubleshooting article for the user’s version.
6. Prefer reversible remediation - Retry, refresh status, fix permissions/connectivity, restore configuration, or complete documented repair steps before deletion/recreation.
7. Validate and document - Confirm resource state, Arc connectivity, workload health, and monitoring after remediation.

Scenario routing

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.

Related references

• MCP and CLI tools
• Resource types and ARG patterns
• Safety rules
• Azure Local docs map