Windows Remote Desktop Connection Doctor

Windows Remote Desktop Connection Doctor

Diagnose and fix Windows App (AVD/WVD/W365) connection quality issues on macOS, with focus on transport protocol optimization.

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.

Diagnostic Workflow

Step 1: Collect Connection Info

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.

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.

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

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

Compare Working vs Broken Logs

When possible, compare a log from when the connection worked (UDP) with the current log:

# Compare startup health check blocks
for f in "$LOG_DIR"/*.log; do
  echo "=== $(basename "$f") ==="
  grep -E "InternetConnectivity|Routed Through VPN|Passed URL|FetchClient" "$f" | head -10
  echo ""
done

A working log will contain the full health check block (InternetConnectivity, VPN routing detection, gateway URL tests). A broken log may show these entries missing entirely, or show certificate/timeout errors instead.

Step 4: Determine Root Cause

Based on collected evidence, identify the root cause category:

Category A: VPN/Proxy Interference

Evidence: Windows App source IP is 198.18.0.x, STUN/TURN routed through VPN, no UDP connections.

Fix: Add DIRECT rules for AVD traffic in the proxy tool:

DOMAIN-SUFFIX,wvd.microsoft.com,DIRECT
DOMAIN-SUFFIX,microsoft.com,DIRECT
IP-CIDR,13.104.0.0/14,DIRECT

Verify: Temporarily disable VPN/proxy, reconnect VDI, check if transport changes to UDP.

Category B: ISP/Network UDP Restriction

Evidence: Even with all VPNs off, still WebSocket. No UDP connections. FetchClientOptions timeout.

Verify:

# Test STUN connectivity to a known server
python3 -c "
import socket, struct, os
header = struct.pack('!HHI', 0x0001, 0, 0x2112A442) + os.urandom(12)
for srv in [('stun.l.google.com', 19302), ('stun1.l.google.com', 19302)]:
    try:
        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
        s.settimeout(3)
        s.sendto(header, srv)
        data, addr = s.recvfrom(1024)
        print(f'STUN from {srv[0]}: OK')
        s.close(); break
    except: print(f'STUN from {srv[0]}: FAILED'); s.close()
"

Fix options:

• Try mobile hotspot (isolate home network from ISP)
• Check router NAT type (Full Cone NAT preferred)
• Enable UPnP on router
• Try IPv6 if available
• Contact ISP about UDP restrictions

Category C: Client Health Check Failure

Evidence: Log shows certificate validation errors at startup, health check block (InternetConnectivity, STUN/TURN detection) missing from log, FetchClientOptions timeout.

This means the client cannot complete its diagnostic/capability discovery, preventing Shortpath negotiation.

Possible causes:

• ISP HTTPS interception/MITM (especially in China)
• DNS poisoning returning incorrect IPs for Microsoft diagnostic endpoints
• Firewall blocking Microsoft telemetry endpoints

Fix options:

• Change DNS to 8.8.8.8 or 1.1.1.1 (bypass ISP DNS)
• Route Microsoft traffic through a clean proxy
• Check if ISP injects certificates

Category D: Server-Side Shortpath Not Enabled

Evidence: Log shows no STUN/TURN or Shortpath related entries at all (not even detection), but health checks pass and no errors.

This means the AVD host pool does not have RDP Shortpath enabled. This requires admin action on the Azure portal.

Step 5: Verify Fix

After applying a fix, reconnect the VDI session and verify:

1. Check Connection Info — Transport Protocol should show UDP or UDP Multicast 2. RTT should drop significantly (e.g., from 165ms to 40-60ms) 3. Verify with lsof:

lsof -i UDP -n -P 2>/dev/null | grep -i "Windows"
# Should show UDP connections if Shortpath is active

References

• references/windows_app_log_analysis.md — Detailed log parsing patterns, error signatures, and comparison methodology
• references/avd_transport_protocols.md — How AVD transport selection works, STUN/TURN/ICE overview, Shortpath architecture

AVD Transport Protocol Reference

How Azure Virtual Desktop selects transport protocols and how RDP Shortpath works.

Contents

• Transport protocol hierarchy
• RDP Shortpath architecture
• STUN/TURN/ICE overview
• Why Shortpath fails
• Network requirements
• Common interference patterns

Transport Protocol Hierarchy

Azure Virtual Desktop clients attempt transports in this order:

1. UDP Shortpath (best) — Direct UDP connection via ICE/STUN/TURN 2. TCP — Direct TCP connection to session host 3. WebSocket — WebSocket over TCP 443 through the AVD gateway (worst)

The client always establishes a WebSocket connection to the gateway first (for control plane). Then it attempts to upgrade to UDP Shortpath. If Shortpath negotiation fails, the session data stays on the WebSocket channel.

RDP Shortpath Architecture

For Public Networks (most common for remote workers)

RDP Shortpath for public networks uses ICE, STUN, and TURN protocols to establish a direct UDP connection between client and session host:

1. Client connects to AVD gateway via WebSocket (TCP 443) 2. Through this control channel, ICE negotiation begins 3. Client and server gather ICE candidates using STUN 4. They exchange candidates and attempt connectivity checks 5. If a direct UDP path exists, Shortpath is established 6. If direct fails but TURN relay is available, traffic relays through TURN 7. If all UDP attempts fail, session stays on WebSocket

For Managed Networks (corporate LAN)

When client and session host are on the same network, Shortpath uses direct UDP without STUN/TURN. This is the simplest mode and rarely fails.

STUN/TURN/ICE Overview

STUN (Session Traversal Utilities for NAT)

STUN discovers the client's public IP and port as seen from outside the NAT. The client sends a STUN Binding Request to a STUN server, which replies with the client's observed address.

Key port: UDP 3478

NAT types that affect STUN:

• Endpoint-Independent Mapping (EIM): Best — same public port regardless of destination. STUN works reliably.
• Address-Dependent Mapping: Moderate — different public port per destination IP. STUN may work with help from TURN.
• Address-and-Port-Dependent (Symmetric NAT): Worst — different public port per destination IP:port. STUN alone often fails; requires TURN relay.

TURN (Traversal Using Relays around NAT)

When direct UDP fails, TURN provides a relay server. Traffic goes: Client → TURN server → Session Host. Adds latency but still uses UDP.

Key ports: UDP 3478, TCP 443 (fallback)

ICE (Interactive Connectivity Establishment)

ICE orchestrates STUN and TURN to find the best available path. It gathers candidates (direct, server-reflexive via STUN, relayed via TURN), exchanges them with the peer, and tests connectivity.

Why Shortpath Fails

1. VPN/Proxy TUN Hijacking

When a VPN tool (ShadowRocket, Clash, Surge) runs in TUN mode, it captures all outbound traffic including STUN/TURN UDP packets. The proxy typically cannot relay raw UDP correctly, causing ICE negotiation to fail.

Detection: Windows App's source IP in lsof shows 198.18.0.x (ShadowRocket) or another VPN virtual IP instead of the real local IP.

2. ISP UDP Restrictions

Some ISPs (particularly in China, especially outside tier-1 cities) throttle or block UDP to certain ports or destinations. This prevents STUN binding requests from reaching Azure's STUN servers.

Detection: STUN tests fail even with all VPNs disabled.

3. Symmetric NAT (Address-and-Port-Dependent)

If the router implements symmetric NAT, each outbound UDP flow gets a different public port. STUN discovers one port, but when the actual Shortpath connection uses a different destination, the NAT assigns a different port, and the peer's packets go to the wrong port.

Detection: Tailscale netcheck shows MappingVariesByDestIP: true.

4. FetchClientOptions Timeout

The client needs to fetch transport capabilities from the gateway. If this request times out (network issues, DNS problems, TLS interception), the client never learns about Shortpath availability.

Detection: Log entry CWVDTransport::FetchClientOptions exception: Request timed out.

5. Health Check Failure

Certificate validation errors at app startup prevent the diagnostic subsystem from completing, which can cascade into transport capability discovery failures.

Detection: Failed to validate X509CertificateChain at the start of the log, followed by absence of the health check block.

6. Server-Side Not Enabled

RDP Shortpath must be enabled on the AVD host pool by an administrator. If not enabled, the server never offers Shortpath candidates.

Detection: No STUN/TURN/Shortpath entries at all in logs, even though health checks pass.

Network Requirements for Shortpath

Ports

DNS

The client must resolve these domains correctly:

• *.wvd.microsoft.com — AVD gateway
• rdweb.wvd.microsoft.com — AVD web client
• STUN/TURN server addresses (provided by the gateway during ICE)

DNS poisoning (returning fake IPs) prevents proper transport negotiation.

TLS

The client validates TLS certificates for Microsoft endpoints. If the certificate chain is modified (ISP proxy, corporate MITM, DNS poisoning), the health check fails and transport negotiation may be impaired.

Common Interference Patterns

Pattern: ShadowRocket TUN Mode

Mechanism: Creates utun interface with IP 198.18.0.1, captures all public traffic via 0/1 + 128.0/1 split routing, DNS hijacked to 198.18.0.2.

Effect on RDP: All AVD traffic goes through proxy tunnel. STUN/TURN fails because proxy cannot relay raw UDP. DNS returns fake IPs (198.18.0.x).

Fix: Add DIRECT rules for Microsoft/Azure domains and IPs.

Pattern: Tailscale with Exit Node

Mechanism: When exit node is enabled, all traffic routes through the Tailscale tunnel.

Effect on RDP: Similar to VPN hijacking — UDP packets go through WireGuard tunnel to exit node, then to Azure. Adds latency and may break STUN.

Fix: Disable exit node, or add route exceptions for Azure IPs.

Pattern: Chinese ISP UDP Throttling

Mechanism: Some Chinese ISPs, particularly in non-tier-1 cities, apply QoS policies that throttle or drop UDP packets to foreign destinations.

Effect on RDP: STUN binding requests time out. Even with perfect client-side configuration, Shortpath cannot establish.

Fix: Try mobile hotspot (different ISP/carrier), use a proxy with good UDP support to Azure's region, or accept WebSocket with optimization (change DNS to reduce resolution latency).

Windows App Log Analysis Guide

Detailed patterns for parsing Windows App (Microsoft Remote Desktop) diagnostic logs on macOS.

Contents

• Log file locations
• Log file naming and rotation
• Startup health check block
• Transport negotiation entries
• Error signatures and their meaning
• Comparing working vs broken sessions
• Filtering noise from logs

Log File Locations

macOS

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

Files follow the pattern:

com.microsoft.rdc.macos_v<version>_<YYYY-MM-DD>_<HH-mm-ss>.log

A new log file is created each day or when the app restarts. Multiple files may exist — sort by modification time to find the most recent:

ls -lt ~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App/

Startup Health Check Block

When the Windows App launches, it runs a health check sequence. A healthy startup produces entries in this order:

Passed: InternetConnectivity
0: 1
4: 3
AvcDecodingCheck: 0
HardwarePresenterCheck: 0
AvcHwDecodingCheck: 1
4: 4
TCP/IP Traffic Routed Through VPN: No
STUN/TURN Traffic Routed Through VPN: Yes

Followed by gateway reachability tests:

Passed URL: https://afdfp-rdgateway-r1.wvd.microsoft.com/ Attempts Made: 1 Used Ipv4: 1 HTTP Status Code: 200 Response Time: 480
Passed URL: https://rdweb.wvd.microsoft.com/ Attempts Made: 1 Used Ipv4: 1 HTTP Status Code: 200 Response Time: 613

What Each Entry Means

When Health Check Fails

If the startup health check block is completely absent from a log, the diagnostic subsystem itself failed. Check for certificate validation errors near the log start:

DIAGNOSTICS(ERR): Failed to validate X509CertificateChain, certificate is not trusted.
BASIX_DCT(ERR): OSSLClosingException thrown, msg=Certificate validation failed

This indicates TLS interception (common with ISP HTTPS proxies in China) or DNS poisoning affecting Microsoft diagnostic endpoints.

Transport Negotiation Entries

FetchClientOptions

This is the critical function that retrieves transport capabilities from the gateway:

GATEWAY(ERR): CWVDTransport::FetchClientOptions exception when attempting to fetch client options: Request timed out
    wvd_transport.cpp(521): FetchClientOptions()

When this times out, the client cannot discover available transport options (including Shortpath). The connection will fall back to WebSocket.

ClientOptions Controller

A separate mechanism that refreshes client properties:

ClientOptions_Controller(ERR): ClientOptionsController RefreshProperties attempt 1 failed: Request timed out. Retrying in 30s...
    client_options.cpp(214): RefreshProperties()

This is less critical than FetchClientOptions but indicates general connectivity issues to Microsoft configuration services.

WebRTC Session

A3CORE(ERR): OnRDWebRTCRedirectorRpc rtcSession not handled

This appears when the server sends a WebRTC session setup but the client does not process it. This may indicate incomplete Shortpath support in the client version, or a session setup that arrives after fallback.

Note: OnRDWebRTCRedirectorRpc notifyClipRectChanged not handled is a benign clipboard-related message, not transport-related.

Error Signatures

Certificate Validation Failure

DIAGNOSTICS(ERR): Failed to validate X509CertificateChain, certificate is not trusted.
A3CORE(ERR): ITrustDelegateAdaptorPtr is empty.
BASIX_DCT(ERR): OSSLClosingException thrown, msg=Certificate validation failed, ossl error string="error:00000000:lib(0)::reason(0)", closing error code=1002

Cause: TLS certificate for Microsoft diagnostic endpoints is not trusted. Common with ISP HTTPS proxies/MITM, DNS poisoning, or corporate proxy servers.

Impact: Prevents the diagnostic health check from completing, which may block transport capability discovery.

Channel Write Failures

"-legacy-"(ERR): Channel::StartWrite failed

Multiple consecutive StartWrite failed errors indicate a connection disruption — the WebSocket or TCP connection to the gateway was interrupted. This is typically followed by a reconnection attempt.

Diagnostics Flush Errors

DIAGNOSTICS(ERR): FlushTracesInternal() is called before BeginUpload(). we don't have a claims token yet

This is a benign telemetry error — the diagnostics system tried to upload traces before authentication completed. Does NOT affect connection quality.

Comparing Working vs Broken Sessions

The most effective diagnostic approach: compare a log from when the connection was healthy (UDP transport) with the current broken log.

Quick Comparison Script

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

echo "=== Health check and transport entries per log file ==="
for f in "$LOG_DIR"/*.log; do
  echo ""
  echo "--- $(basename "$f") ---"
  grep -c "InternetConnectivity" "$f" 2>/dev/null | xargs -I{} echo "  InternetConnectivity checks: {}"
  grep "Routed Through VPN" "$f" 2>/dev/null | head -2 | sed 's/^/  /'
  grep "Passed URL:" "$f" 2>/dev/null | head -2 | sed 's/^/  /'
  grep "FetchClientOptions" "$f" 2>/dev/null | head -1 | sed 's/^/  /'
  grep "Certificate validation failed" "$f" 2>/dev/null | head -1 | sed 's/^/  /'
done

What to Compare

Filtering Noise

Windows App logs contain many repetitive entries that obscure useful information. Filter these out:

grep -v -E "BasicStateManagement|DynVC.*SendChannelClose|dynvcstat.*SerializeToJson|asynctransport\.cpp|FlushTracesInternal"

Common Noise Patterns

The last pattern (Stateful object destructed in Opened state) may be significant during active troubleshooting — it indicates connections being torn down unexpectedly. Keep it when investigating disconnection events.

Activity ID Tracking

Each RDP session gets a unique activity ID (GUID). Track a specific session through the log:

# Find activity IDs from connection events
grep -E "\{[0-9a-f]{8}-" "$LOG_FILE" | grep -v "00000000-0000-0000-0000-000000000000" | head -5

# Trace a specific session
grep "<activity-id>" "$LOG_FILE" | grep -v "BasicStateManagement\|FlushTraces"

The null GUID {00000000-0000-0000-0000-000000000000} indicates background/system events, not specific RDP sessions.