Prompt
How do I diagnose NAT traversal problems in WebRTC
Latest observation
To diagnose NAT traversal problems in WebRTC, focus on where connectivity fails in the ICE process and then inspect candidate gathering, signaling, connectivity checks, and relay fallback.
1) Know the WebRTC NAT traversal path
WebRTC uses ICE to find a working path between peers. It can try:
- Host candidates: direct local IPs
- Srflx candidates: server-reflexive addresses learned via STUN
- Relay candidates: addresses via TURN
If direct P2P fails, a healthy setup should usually fall back to TURN relay.
2) Check the ICE state
In the browser, inspect:
iceGatheringStateiceConnectionStateconnectionState
Typical failure patterns:
iceGatheringStatestuck atgatheringorcompletewith few/no candidatesiceConnectionStategoescheckingthenfailedconnected/completednever reached
Use:
- Chrome:
chrome://webrtc-internals - Firefox:
about:webrtc
These pages show:
- gathered candidates
- selected pair
- ICE errors
- STUN/TURN server responses
- consent checks
3) Verify candidate gathering
Inspect the ICE candidates produced by each peer.
You want to see:
- host candidates
- srflx candidates from STUN
- relay candidates from TURN
Red flags:
- Only host candidates appear
- No srflx candidates from STUN
- No relay candidates from TURN
- Candidates are gathered, but remote never receives them
Common causes:
- STUN/TURN misconfiguration
- signaling path dropping candidates
- browser or OS network restrictions
- IPv6-only / IPv4-only mismatch
4) Confirm signaling is working
ICE candidates must be exchanged over your signaling channel.
Check:
- SDP offer/answer exchange completes
onicecandidatemessages are sent and received- Trickle ICE candidates arrive at the remote peer
- End-of-candidates is handled correctly
Problems here often look like NAT issues, but are actually signaling bugs.
5) Test STUN independently
Use a known-good STUN server and confirm you get a server-reflexive candidate.
Examples:
stun.l.google.com:19302- your own STUN server
If STUN fails:
- UDP may be blocked
- DNS may be failing
- network may be behind restrictive firewall/proxy
- the server may not support the transport you’re using
6) Test TURN independently
TURN is the usual fallback when NAT is symmetric or firewalls block direct paths.
Check:
- TURN credentials are valid
- TURN server is reachable on expected ports
- UDP, TCP, and TLS relays are configured if needed
- authentication succeeds
- relay candidates appear in ICE
If TURN doesn’t work:
- wrong username/password or time-limited credentials expired
- firewall blocks TURN ports
- server only listening on one transport
- TLS/certificate issues for
turns:
7) Inspect the selected candidate pair
In debugging tools, look at the candidate pair that ICE ultimately selects:
- local candidate type
- remote candidate type
- protocol (UDP/TCP)
- IP family (IPv4/IPv6)
- state and priority
This tells you whether the connection is:
- direct host-host
- srflx-srflx
- host-relay
- srflx-relay
- relay-relay
If the selected pair is always relay, NAT is likely preventing direct connectivity.
8) Look for NAT type clues
Some NAT/firewall combinations are especially problematic:
- Symmetric NAT
- CGNAT
- strict enterprise firewalls
- UDP-blocking networks
Symptoms:
- STUN works inconsistently or not at all
- only TURN relay succeeds
- direct P2P fails from some networks but not others
A practical test:
- try the same setup on home Wi‑Fi, mobile hotspot, and corporate network
- if only one network works, the issue is likely NAT/firewall policy
9) Use ICE diagnostics/logging
Enable verbose logging in your app:
- log every ICE candidate
- log ICE state transitions
- log SDP offers/answers
- log STUN/TURN URLs and transport
In Chromium-based browsers, webrtc-internals provides:
- ICE candidate pairs
- STUN transactions
- selected transport
- stats like RTT, packets sent/received, bytes, retransmissions
Useful WebRTC stats:
RTCIceCandidatePairStatsRTCTransportStatsRTCInboundRtpStreamStats/RTCOutboundRtpStreamStats
10) Check common configuration issues
STUN/TURN URL mistakes
- wrong scheme:
stun:,turn:,turns: - wrong port
- wrong IP version
- TURN server not supporting UDP/TCP/TLS as expected
ICE server config
Make sure you pass something like:
const pc = new RTCPeerConnection({
iceServers: [
{ urls: "stun:stun.l.google.com:19302" },
{
urls: "turn:turn.example.com:3478",
username: "user",
credential: "pass"
}
]
});
CORS/signaling
Not directly NAT, but if signaling is broken, ICE will never complete.
mDNS host candidates
Modern browsers may obfuscate local IPs. That’s normal, but can complicate debugging.
11) Reproduce with controlled test cases
Try:
- same LAN vs different networks
- IPv4-only vs IPv6-only
- one peer behind NAT, one public IP
- UDP blocked vs allowed
- TURN-only mode
You can force TURN-only temporarily by setting policy options or by filtering candidate use in your app during testing. If TURN works but direct doesn’t, it strongly suggests NAT traversal issues rather than signaling failure.
12) Practical troubleshooting checklist
- Open
webrtc-internals - Confirm offer/answer exchange
- Confirm candidates are gathered and exchanged
- Confirm STUN produces srflx candidates
- Confirm TURN produces relay candidates
- Check ICE state transitions
- Inspect selected candidate pair
- Compare behavior across networks
- Verify firewall/ports/UDP/TCP/TLS
- Try TURN-only as a fallback test
13) If you want a quick decision tree
- No candidates at all → signaling or browser/network API issue
- Host candidates only → STUN blocked or misconfigured
- Srflx exists but no connection → NAT/firewall or remote candidate exchange issue
- Direct fails but TURN works → NAT traversal problem; use TURN fallback
- TURN fails too → server/credentials/ports/firewall issue
If you want, I can also give you:
- a step-by-step debugging workflow for Chrome/Firefox, or
- a small WebRTC stats script that prints the selected ICE candidate pair and common failure clues.