1# TURN Gotchas & Troubleshooting
2 
3Common mistakes, security best practices, and troubleshooting for Cloudflare TURN.
4 
5## Quick Reference
6 
7| Issue | Solution | Details |
8|-------|----------|---------|
9| Credentials not working | Check TTL ≤ 48hrs | [See Troubleshooting](#issue-turn-credentials-not-working) |
10| Connection drops after ~48hrs | Implement credential refresh | [See Connection Drops](#issue-connection-drops-after-48-hours) |
11| Port 53 fails in browser | Filter server-side | [See Port 53](#using-port-53-in-browsers) |
12| High packet loss | Check rate limits | [See Rate Limits](#limits-per-turn-allocation) |
13| Connection fails after maintenance | Implement ICE restart | [See ICE Restart](#ice-restart-required-scenarios) |
14 
15## Critical Constraints
16 
17| Constraint | Value | Consequence if Violated |
18|------------|-------|-------------------------|
19| Max credential TTL | 48 hours (172800s) | API rejects request |
20| Credential revocation delay | ~seconds | Billing stops immediately, connection drops shortly |
21| IP allowlist update window | 14 days (if IPs change) | Connection fails if IPs change |
22| Packet rate | 5-10k pps per allocation | Packet drops |
23| Data rate | 50-100 Mbps per allocation | Packet drops |
24| Unique IP rate | >5 new IPs/sec | Packet drops |
25 
26## Limits Per TURN Allocation
27 
28**Per user** (not account-wide):
29 
30- **IP addresses**: >5 new unique IPs per second
31- **Packet rate**: 5-10k packets per second (inbound/outbound)
32- **Data rate**: 50-100 Mbps (inbound/outbound)
33- **MTU**: No specific limit
34- **Burst rates**: Higher than documented
35 
36Exceeding limits results in **packet drops**.
37 
38## Common Mistakes
39 
40### Setting TTL > 48 hours
41 
42```typescript
43// ❌ BAD: API will reject
44const creds = await generate({ ttl: 604800 });  // 7 days
45 
46// ✅ GOOD:
47const creds = await generate({ ttl: 86400 });   // 24 hours
48```
49 
50### Hardcoding IPs without monitoring
51 
52```typescript
53// ❌ BAD: IPs can change with 14-day notice
54const iceServers = [{ urls: 'turn:141.101.90.1:3478' }];
55 
56// ✅ GOOD: Use DNS
57const iceServers = [{ urls: 'turn:turn.cloudflare.com:3478' }];
58```
59 
60### Using port 53 in browsers
61 
62```typescript
63// ❌ BAD: Blocked by Chrome/Firefox
64urls: ['turn:turn.cloudflare.com:53']
65 
66// ✅ GOOD: Filter port 53
67urls: urls.filter(url => !url.includes(':53'))
68```
69 
70### Not handling credential expiry
71 
72```typescript
73// ❌ BAD: Credentials expire but call continues → connection drops
74const creds = await fetchCreds();
75const pc = new RTCPeerConnection({ iceServers: creds });
76 
77// ✅ GOOD: Refresh before expiry
78setInterval(() => refreshCredentials(pc), 3000000);  // 50 min
79```
80 
81### Missing ICE restart support
82 
83```typescript
84// ❌ BAD: No recovery from TURN maintenance
85pc.addEventListener('iceconnectionstatechange', () => {
86  console.log('State changed:', pc.iceConnectionState);
87});
88 
89// ✅ GOOD: Implement ICE restart
90pc.addEventListener('iceconnectionstatechange', async () => {
91  if (pc.iceConnectionState === 'failed') {
92    await refreshCredentials(pc);
93    pc.restartIce();
94  }
95});
96```
97 
98### Exposing TURN key secret client-side
99 
100```typescript
101// ❌ BAD: Secret exposed to client
102const secret = 'your-turn-key-secret';
103const response = await fetch(`https://rtc.live.cloudflare.com/v1/turn/...`, {
104  headers: { 'Authorization': `Bearer ${secret}` }
105});
106 
107// ✅ GOOD: Generate credentials server-side
108const response = await fetch('/api/turn-credentials');
109```
110 
111## ICE Restart Required Scenarios
112 
113These events require ICE restart (see [patterns.md](./patterns.md#ice-restart-pattern)):
114 
1151. **TURN server maintenance** (occasional on Cloudflare's network)
1162. **Network topology changes** (anycast routing changes)
1173. **Credential refresh** during long sessions (>1 hour)
1184. **Connection failure** (iceConnectionState === 'failed')
119 
120Implement in all production apps:
121 
122```typescript
123pc.addEventListener('iceconnectionstatechange', async () => {
124  if (pc.iceConnectionState === 'failed' || 
125      pc.iceConnectionState === 'disconnected') {
126    await refreshTURNCredentials(pc);
127    pc.restartIce();
128    const offer = await pc.createOffer({ iceRestart: true });
129    await pc.setLocalDescription(offer);
130    // Send offer to peer via signaling...
131  }
132});
133```
134 
135Reference: [RFC 8445 Section 2.4](https://datatracker.ietf.org/doc/html/rfc8445#section-2.4)
136 
137## Security Checklist
138 
139- [ ] Credentials generated server-side only (never client-side)
140- [ ] TURN_KEY_SECRET in wrangler secrets, not vars
141- [ ] TTL ≤ expected session duration (and ≤ 48 hours)
142- [ ] Rate limiting on credential generation endpoint
143- [ ] Client authentication before issuing credentials
144- [ ] Credential revocation API for compromised sessions
145- [ ] No hardcoded IPs (or DNS monitoring in place)
146- [ ] Port 53 filtered for browser clients
147 
148## Troubleshooting
149 
150### Issue: TURN credentials not working
151 
152**Check:**
153- Key ID and secret are correct
154- Credentials haven't expired (check TTL)
155- TTL doesn't exceed 172800 seconds (48 hours)
156- Server can reach rtc.live.cloudflare.com
157- Network allows outbound HTTPS
158 
159**Solution:**
160```typescript
161// Validate before using
162if (ttl > 172800) {
163  throw new Error('TTL cannot exceed 48 hours');
164}
165```
166 
167### Issue: Slow connection establishment
168 
169**Solutions:**
170- Ensure proper ICE candidate gathering
171- Check network latency to Cloudflare edge
172- Verify firewall allows WebRTC ports (3478, 5349, 443)
173- Consider using TURN over TLS (port 443) for corporate networks
174 
175### Issue: High packet loss
176 
177**Check:**
178- Not exceeding rate limits (5-10k pps)
179- Not exceeding bandwidth limits (50-100 Mbps)
180- Not connecting to too many unique IPs (>5/sec)
181- Client network quality
182 
183### Issue: Connection drops after ~48 hours
184 
185**Cause**: Credentials expired (48hr max)
186 
187**Solution**: 
188- Set TTL to expected session duration
189- Implement credential refresh with setConfiguration()
190- Use ICE restart if connection fails
191 
192```typescript
193// Refresh credentials before expiry
194const refreshInterval = ttl * 1000 - 60000; // 1 min early
195setInterval(async () => {
196  await refreshTURNCredentials(pc);
197}, refreshInterval);
198```
199 
200### Issue: Port 53 URLs in browser fail silently
201 
202**Cause**: Chrome/Firefox block port 53
203 
204**Solution**: Filter port 53 URLs server-side:
205 
206```typescript
207const filtered = urls.filter(url => !url.includes(':53'));
208```
209 
210### Issue: Hardcoded IPs stop working
211 
212**Cause**: Cloudflare changed IP addresses (14-day notice)
213 
214**Solution**: 
215- Use DNS hostnames (`turn.cloudflare.com`)
216- Monitor DNS changes with automated alerts
217- Update allowlists within 14 days if using IP allowlisting
218 
219## Cost Optimization
220 
2211. Use appropriate TTLs (don't over-provision)
2222. Implement credential caching
2233. Set `iceTransportPolicy: 'all'` to try direct first (use `'relay'` only when necessary)
2244. Monitor bandwidth usage
2255. Free when used with Cloudflare Calls SFU
226 
227## See Also
228 
229- [api.md](./api.md) - Credential generation API, revocation
230- [configuration.md](./configuration.md) - IP allowlisting, monitoring
231- [patterns.md](./patterns.md) - ICE restart, credential refresh patterns
232