1# Cannot Connect to VM
2 
3Index of VM connectivity troubleshooting references. Route to the appropriate file based on the user's symptom category.
4 
5> ⚠️ **Determine OS first.** If the user hasn't stated their OS, check via CLI (`az vm get-instance-view`) or ask. OS matters because:
6> - **Windows** → RDP (port 3389), Windows Firewall, TermService, PowerShell Run Commands
7> - **Linux** → SSH (port 22), iptables/firewalld/UFW, sshd, Shell Run Commands
8> - **Other images** (FreeBSD, Flatcar, etc.) → SSH; firewall and init systems vary — fetch the latest docs
9 
10## Routing
11 
12| Signal in User Message                                                         | Category                  | Reference                                                  |
13| ------------------------------------------------------------------------------ | ------------------------- | ---------------------------------------------------------- |
14| "can't RDP", timeout, black screen, RDP error, internal error                  | Unable to RDP             | [rdp-connectivity.md](rdp-connectivity.md)                 |
15| "can't SSH", refused, permission denied, publickey                             | Unable to SSH             | [ssh-connectivity.md](ssh-connectivity.md)                 |
16| NSG, no public IP, NIC disabled, routing, effective rules                      | Network Issues            | [network-connectivity.md](network-connectivity.md)         |
17| Guest firewall, Windows Firewall, iptables, firewalld, BlockInboundAlways      | Firewall Blocking         | [firewall-blocking.md](firewall-blocking.md)               |
18| VM agent down, Run Command timeout, Serial Console, boot diagnostics, BSOD     | VM Agent Not Responding   | [vm-agent-not-responding.md](vm-agent-not-responding.md)   |
19| Wrong password, credentials, access denied, CredSSP, account expired           | Credential / Auth Errors  | [credential-auth-errors.md](credential-auth-errors.md)     |
20| TermService stopped, RDP disabled, port changed, TLS cert, NLA, GPO, licensing | RDP Service / Config      | [rdp-service-config.md](rdp-service-config.md)             |
21 
22## Workflow
23 
241. Identify the symptom category from the routing table above
252. Open the matching reference file for the Symptoms → Solutions table and Quick Commands
263. Narrow to the specific solution row matching the user's symptom
274. **Before any extension-backed operation, run [Pre-Flight Safety Checks](#pre-flight-safety-checks)**
285. Fetch the linked documentation URL for the latest guidance
296. Summarize diagnostic steps and resolution, referencing the official docs
30 
31---
32 
33## Pre-Flight Safety Checks
34 
35> ⚠️ **Warning:** Always run these checks before any command that depends on the VM agent or extensions (`az vm user update`, `az vm user reset-ssh`, `az vm user reset-remote-desktop`, `az vm run-command invoke`). Running extension-backed operations on a VM with an unhealthy agent or stuck extensions can **deadlock the VM** and require manual portal recovery.
36 
37```bash
38# 1. Check VM power state, provisioning state, and agent status
39az vm get-instance-view --name <vm-name> -g <resource-group> \
40  --query "instanceView.{powerState:[statuses[?starts_with(code,'PowerState/')]][0][0].code, provisioningState:[statuses[?starts_with(code,'ProvisioningState/')]][0][0].code, vmAgentStatus:vmAgent.statuses[0].displayStatus}" -o json
41 
42# 2. Check existing extension states
43az vm extension list --vm-name <vm-name> -g <resource-group> \
44  --query "[].{name:name, provisioningState:provisioningState}" -o table
45```
46 
47| Check | Safe Value | Unsafe — Do NOT proceed |
48| ----- | ---------- | ----------------------- |
49| Power state | `PowerState/running` | Any other value, missing, or query error |
50| Provisioning state | `ProvisioningState/succeeded` | `Updating`, `Creating`, `Failed`, `Deleting`, missing, or query error |
51| VM agent status | `Ready` | `Not Ready`, `null`, missing, or query error |
52| Extension states | All `Succeeded` or no extensions | Any extension in `Creating`, `Updating`, `Deleting`, or `Failed` |
53 
54> 💡 **Tip:** If a check returns `null`, empty, or the CLI command itself errors, treat the result as **unsafe**.
55 
56**If any check is unsafe:**
571. **Stop.** Do NOT run any extension-backed command.
582. Inform the user which check(s) failed and what the current state is.
593. Use non-agent alternatives: **Serial Console**, **offline repair VM**, or **Portal-based actions**.
604. If the state appears transient (e.g., VM just started, provisioning briefly not `succeeded`), wait 30–60 seconds and **re-run the checks only** — do not run the extension command until all checks pass.
61 
62---
63 
64## Escalation
65 
66If the issue doesn't match any symptom above, or if the documented solutions don't resolve it:
67 
681. **Check Azure Resource Health** — Portal > VM > Resource health (checks for platform-level issues)
692. **Offer to restart the VM** (requires user approval) — `az vm restart --name <vm-name> -g <resource-group>`
703. **Offer to redeploy the VM** (requires user approval — moves to new host) — `az vm redeploy --name <vm-name> -g <resource-group>`
714. **Comprehensive troubleshooting:**
72   - Windows: [Troubleshoot RDP connections](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-machines/windows/troubleshoot-rdp-connection)
73   - Linux: [Troubleshoot SSH connections](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-machines/linux/troubleshoot-ssh-connection)
74   - Windows hub: [All Windows VM troubleshooting docs](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-machines/windows/welcome-virtual-machines-windows)
75   - Linux hub: [All Linux VM troubleshooting docs](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-machines/linux/welcome-virtual-machines-linux)