Debugging WebRTC that connects on Wi‑Fi but never on cellular

Almost certainly: you have STUN but no TURN, and the cellular path needs TURN.

Why: on cellular the phone is behind carrier-grade NAT (often symmetric NAT). STUN tells each side its public address, but with symmetric NAT the port the Mac learns is not the port the phone will actually use for that peer, so every candidate pair fails the connectivity check. That’s exactly the “stuck in checking” symptom. On Wi‑Fi both devices see each other’s host candidates directly, so it never mattered.

Checklist:

1. Add a TURN server (coturn, or a hosted one). Include both turn: on UDP 3478 and turns: on TCP 443 — some carriers throttle or block UDP, and 443/TCP is the one thing that always gets through.
2. Use short-lived TURN credentials (HMAC-based username:timestamp + shared secret). Never ship a static TURN password in the app; it will be extracted and your relay bill will fund someone else’s video calls.
3. On iOS, make sure the Mac side isn’t only offering IPv4 candidates while the phone is IPv6-only on cellular (common with some carriers). TURN sidesteps that too, but it’s worth logging the candidate types you get.
4. Log iceConnectionState transitions with timestamps and dump the selected candidate pair via getStats() — once TURN is in, you want to see relay pairs on cellular and host/srflx pairs on Wi‑Fi.

Expect roughly 30–80 ms extra latency through the relay, depending on where the TURN server sits. Put it in the same region as most of your users.

Configure it on both peers. ICE picks the working pair, and having relay candidates from both sides makes the connection succeed in more NAT combinations (e.g. when the home router is the strict one, not the carrier). In practice only one side will end up relaying, and on Wi‑Fi neither will — the direct pair wins because it has higher priority.