Windows Remote Desktop Connection Doctor

Windows Remote Desktop Connection Doctor

Diagnose and fix Windows App (Microsoft Remote Desktop / AVD / WVD / W365 / direct PC) connection issues on macOS, with focus on transport protocol optimization and root-cause falsification.

Methodology base: the general evidence-driven diagnosis discipline lives in the debugging-network-issues skill. This skill is the Windows-App / AVD transport domain layer — it leans toward connection-quality optimization more than root-cause falsification, so the methodology overlap is lighter.

Background

Azure Virtual Desktop transport priority: UDP Shortpath > TCP > WebSocket. UDP Shortpath provides the best experience (lowest latency, supports UDP Multicast). When it fails, the client falls back to WebSocket over TCP 443 through the gateway, adding significant latency overhead.

Direct PC connections use plain RDP over TCP 3389 (usually TLS-wrapped). They have no Connection Info panel, no gateway reachability tests, and no transport optimization step. For direct PC, the dominant failure modes are:

1. The remote PC is off or unreachable (network/firewall).
2. The Windows App client has a stale or expired Microsoft work/school account that poisons the auth orchestration, leaving the connection stuck at "Configuring remote PC...".
3. The remote PC rebooted (often Windows Update), and the client cannot recover cleanly.

This skill handles both scenarios.

Diagnostic Workflow

Step 1: Determine the Connection Type and Symptom

Before collecting evidence, identify which scenario you are diagnosing:

For AVD/WVD/W365, ask the user to provide the Connection Info from Windows App (click the signal icon in the toolbar). Key fields to extract:

If Transport Protocol is UDP or UDP Multicast, the connection is optimal — no further diagnosis needed.

If Transport Protocol is WebSocket or TCP, proceed to Step 2.

For Direct PC, the Connection Info panel does not exist. Instead, first run the RDP protocol probe in Step 2E to prove the server is reachable, then analyze the Windows App log for auth poisoning or reconnect failures. If the progress dialog is stuck at "Configuring remote PC...", strongly suspect client-side identity issues (see Category E).

Step 2: Collect Network Evidence

Gather evidence in parallel — do NOT make assumptions. Run the following checks simultaneously:

2A: Network Interfaces and Routing

ifconfig | grep -E "^[a-z]|inet |utun"
netstat -rn | head -40
scutil --proxy

Look for:

• utun interfaces: Identify VPN/proxy TUN tunnels (ShadowRocket, Clash, Tailscale)
• Default route priority: Which interface handles default traffic
• Split routing: 0/1 + 128.0/1 → utun pattern means a VPN captures all traffic
• System proxy: HTTP/HTTPS proxy enabled on localhost ports

2B: RDP Client Process and Connections

# Find the Windows App process (NOT "msrdc" — the new client uses "Windows" as process name)
ps aux | grep -i -E 'msrdc|Windows' | grep -v grep
# Check its network connections
lsof -i -n -P 2>/dev/null | grep -i "Windows" | head -20
# Check for UDP connections
lsof -i UDP -n -P 2>/dev/null | head -30

Key evidence to look for:

• Source IP `198.18.0.x`: Traffic is being routed through ShadowRocket/proxy TUN tunnel
• No UDP connections from Windows process: Shortpath not established
• Only TCP 443: Fallback to gateway WebSocket transport

2C: VPN/Proxy State

# Environment proxy variables
env | grep -i proxy
# System proxy via scutil
scutil --proxy
# ShadowRocket config API (if accessible on local network)
NO_PROXY="<local-ip>" curl -s --connect-timeout 5 "http://<local-ip>:8080/api/read"

2D: Tailscale State (if running)

tailscale status
tailscale netcheck

The netcheck output reveals NAT type (MappingVariesByDestIP), UDP support, and public IP — valuable even when Tailscale is not the problem.

2E: Independent RDP Server Health Check (Direct PC)

This step is critical for direct PC connections and useful for AVD/WVD/W365 as a falsification test: it proves the server-side RDP stack is alive without relying on the Windows App client or any credentials.

Use the bundled probe script:

python3 scripts/probe_rdp_server.py <host> [port]

Example:

python3 scripts/probe_rdp_server.py my-pc.local 3389

A successful probe reports RDP server <host>:<port> is reachable and healthy (RDP + TLS). and means the problem is client-side (auth, app state, proxy, or identity). A failed probe means the problem is server-side or network (PC off, firewall, port unreachable, TLS interception).

See references/direct_pc_and_auth_diagnostics.md for detailed interpretation of probe results.

Step 3: Analyze Windows App Logs

This is the most critical step. Windows App logs contain transport negotiation details that no network-level test can reveal.

Log location on macOS:

~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows App/

Files are named: com.microsoft.rdc.macos_v<version>_<date>_<time>.log

Important: Windows App log timestamps are UTC. The user's clock and Windows Event logs are usually local time. Convert all timestamps to a single timezone before building a timeline.

Per-session tracking: each connection attempt gets a unique activity GUID in braces. Aggregate events by GUID to understand the lifecycle of one attempt. See references/windows_app_log_analysis.md for the GUID aggregation technique and references/direct_pc_and_auth_diagnostics.md for the direct-PC failure signatures.

See references/windows_app_log_analysis.md for detailed log parsing guidance.

Quick Log Search

LOG_DIR=~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App
# Find the most recent log
LATEST_LOG=$(ls -t "$LOG_DIR"/*.log 2>/dev/null | head -1)

# Search for transport-critical entries (filter out noise)
grep -i -E "STUN|TURN|VPN|Routed|Shortpath|FetchClient|clientoption|GATEWAY.*ERR|Certificate.*valid|InternetConnectivity|Passed URL" "$LATEST_LOG" | grep -v "BasicStateManagement\|DynVC\|dynvcstat\|asynctransport"

Key Log Patterns