1# Gotchas & Troubleshooting
2 
3## Common Errors
4 
5### "Slow initial connect (~1.8s)"
6 
7**Cause:** First STUN delayed during consensus forming (normal behavior)
8**Solution:** Subsequent connections are faster. CF detects DTLS ClientHello early to compensate.
9 
10### "No media flow"
11 
12**Cause:** SDP exchange incomplete, connection not established, tracks not added before offer, browser permissions missing
13**Solution:** 
141. Verify SDP exchange complete
152. Check `pc.connectionState === 'connected'`
163. Ensure tracks added before creating offer
174. Confirm browser permissions granted
185. Use `chrome://webrtc-internals` for debugging
19 
20### "Track not receiving"
21 
22**Cause:** Track not published, track ID not shared, session IDs mismatch, `pc.ontrack` not set, renegotiation needed
23**Solution:** 
241. Verify track published successfully
252. Confirm track ID shared between peers
263. Check session IDs match
274. Set `pc.ontrack` handler before answer
285. Trigger renegotiation if needed
29 
30### "ICE connection failed"
31 
32**Cause:** Network changed, firewall blocked UDP, TURN needed, transient network issue
33**Solution:**
34```typescript
35pc.oniceconnectionstatechange = async () => {
36  if (pc.iceConnectionState === 'failed') {
37    console.warn('ICE failed, attempting restart');
38    await pc.restartIce(); // Triggers new ICE gathering
39    
40    // Create new offer with ICE restart flag
41    const offer = await pc.createOffer({iceRestart: true});
42    await pc.setLocalDescription(offer);
43    
44    // Send to backend → Cloudflare API
45    await fetch(`/api/sessions/${sessionId}/renegotiate`, {
46      method: 'PUT',
47      body: JSON.stringify({sdp: offer.sdp})
48    });
49  }
50};
51```
52 
53### "Track stuck/frozen"
54 
55**Cause:** Sender paused track, network congestion, codec mismatch, mobile browser backgrounded
56**Solution:**
571. Check `track.enabled` and `track.readyState === 'live'`
582. Verify sender active: `pc.getSenders().find(s => s.track === track)`
593. Check stats for packet loss/jitter (see patterns.md)
604. On mobile: Re-acquire tracks when app foregrounded
615. Test with different codecs if persistent
62 
63### "Network change disconnects call"
64 
65**Cause:** Mobile switching WiFi↔cellular, laptop changing networks
66**Solution:**
67```typescript
68// Listen for network changes
69if ('connection' in navigator) {
70  (navigator as any).connection.addEventListener('change', async () => {
71    console.log('Network changed');
72    await pc.restartIce(); // Use ICE restart pattern above
73  });
74}
75 
76// Or use PartyTracks (handles automatically)
77```
78 
79## Retry with Exponential Backoff
80 
81```typescript
82async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
83  for (let i = 0; i < maxRetries; i++) {
84    try {
85      const res = await fetch(url, options);
86      if (res.ok) return res;
87      if (res.status >= 500) throw new Error('Server error');
88      return res; // Client error, don't retry
89    } catch (err) {
90      if (i === maxRetries - 1) throw err;
91      const delay = Math.min(1000 * 2 ** i, 10000); // Cap at 10s
92      await new Promise(resolve => setTimeout(resolve, delay));
93    }
94  }
95}
96```
97 
98## Debugging with chrome://webrtc-internals
99 
1001. Open `chrome://webrtc-internals` in Chrome/Edge
1012. Find your PeerConnection in the list
1023. Check **Stats graphs** for packet loss, jitter, bandwidth
1034. Check **ICE candidate pairs**: Look for `succeeded` state, relay vs host candidates
1045. Check **getStats**: Raw metrics for inbound/outbound RTP
1056. Look for errors in **Event log**: `iceConnectionState`, `connectionState` changes
1067. Export data with "Download the PeerConnection updates and stats data" button
1078. Common issues visible here: ICE failures, high packet loss, bitrate drops
108 
109## Limits
110 
111| Resource/Limit | Value | Notes |
112|----------------|-------|-------|
113| Egress (Free) | 1TB/month | Per account |
114| Egress (Paid) | $0.05/GB | After free tier |
115| Inbound traffic | Free | All plans |
116| TURN service | Free | Included with SFU |
117| Participants | No hard limit | Client bandwidth/CPU bound (typically 10-50 tracks) |
118| Tracks per session | No hard limit | Client resources limited |
119| Session duration | No hard limit | Production calls run for hours |
120| WebRTC ports | UDP 1024-65535 | Outbound only, required for media |
121| API rate limit | 600 req/min | Per app, burst allowed |
122 
123## Security Checklist
124 
125- ✅ **Never expose** `CALLS_APP_SECRET` to client
126- ✅ **Validate user identity** in backend before creating sessions
127- ✅ **Implement auth tokens** for session access (JWT in custom header)
128- ✅ **Rate limit** session creation endpoints
129- ✅ **Expire sessions** server-side after inactivity
130- ✅ **Validate track IDs** before subscribing (prevent unauthorized access)
131- ✅ **Use HTTPS** for all signaling (API calls)
132- ✅ **Enable DTLS-SRTP** (automatic with Cloudflare, encrypts media)
133- ⚠️ **Consider E2EE** for sensitive content (implement client-side with Insertable Streams API)
134