1# RealtimeKit Gotchas & Troubleshooting
2 
3## Common Errors
4 
5### "Cannot connect to meeting"
6 
7**Cause:** Auth token invalid/expired, API credentials lack permissions, or network blocks WebRTC
8**Solution:**
9Verify token validity, check API token has **Realtime / Realtime Admin** permissions, enable TURN service for restrictive networks
10 
11### "No video/audio tracks"
12 
13**Cause:** Browser permissions not granted, video/audio not enabled, device in use, or device unavailable
14**Solution:**
15Request browser permissions explicitly, verify initialization config, use `meeting.self.getAllDevices()` to debug, close other apps using device
16 
17### "Participant count mismatched"
18 
19**Cause:** `meeting.participants` doesn't include `meeting.self`
20**Solution:** Total count = `meeting.participants.joined.size() + 1`
21 
22### "Events not firing"
23 
24**Cause:** Listeners registered after actions, incorrect event name, or wrong namespace
25**Solution:**
26Register listeners before calling `meeting.join()`, check event names against docs, verify correct namespace
27 
28### "CORS errors in API calls"
29 
30**Cause:** Making REST API calls from client-side
31**Solution:** All REST API calls **must** be server-side (Workers, backend). Never expose API tokens to clients.
32 
33### "Preset not applying"
34 
35**Cause:** Preset doesn't exist, name mismatch (case-sensitive), or participant created before preset
36**Solution:**
37Verify preset exists via Dashboard or API, check exact spelling and case, create preset before adding participants
38 
39### "Token reuse error"
40 
41**Cause:** Reusing participant tokens across sessions
42**Solution:** Generate fresh token per session. Use refresh endpoint if token expires during session.
43 
44### "Video quality poor"
45 
46**Cause:** Insufficient bandwidth, resolution/bitrate too high, or CPU overload
47**Solution:**
48Lower `mediaConfiguration.video` resolution/frameRate, monitor network conditions, reduce participant count or grid size
49 
50### "Echo or audio feedback"
51 
52**Cause:** Multiple devices picking up same audio source
53**Solution:**
54- Lower `mediaConfiguration.video` resolution/frameRate
55- Monitor network conditions
56- Reduce participant count or grid size
57 
58### Issue: Echo or audio feedback
59**Cause**: Multiple devices picking up same audio source
60 
61**Solutions**:
62Enable `echoCancellation: true` in `mediaConfiguration.audio`, use headphones, mute when not speaking
63 
64### "Screen share not working"
65 
66**Cause:** Browser doesn't support screen sharing API, permission denied, or wrong `displaySurface` config
67**Solution:**
68Use Chrome/Edge/Firefox (Safari limited support), check browser permissions, try different `displaySurface` values ('window', 'monitor', 'browser')
69 
70### "How do I schedule meetings?"
71 
72**Cause:** RealtimeKit has no built-in scheduling system
73**Solution:**
74Store meeting IDs in your database with timestamps. Generate participant tokens only when user should join. Example:
75```typescript
76// Store in DB
77{ meetingId: 'abc123', scheduledFor: '2026-02-15T10:00:00Z', userId: 'user456' }
78 
79// Generate token when user clicks "Join" near scheduled time
80const response = await fetch('/api/join-meeting', {
81  method: 'POST',
82  body: JSON.stringify({ meetingId: 'abc123' })
83});
84const { authToken } = await response.json();
85```
86 
87### "Recording not starting"
88 
89**Cause:** Preset lacks recording permissions, no active session, or API call from client
90**Solution:**
91Verify preset has `canRecord: true` and `canStartStopRecording: true`, ensure session is active (at least one participant), make recording API calls server-side only
92 
93## Limits
94 
95| Resource | Limit |
96|----------|-------|
97| Max participants per session | 100 |
98| Max concurrent sessions per App | 1000 |
99| Max recording duration | 6 hours |
100| Max meeting duration | 24 hours |
101| Max chat message length | 4000 characters |
102| Max preset name length | 64 characters |
103| Max meeting title length | 256 characters |
104| Max participant name length | 256 characters |
105| Token expiration | 24 hours (default) |
106| WebRTC ports required | UDP 1024-65535 |
107 
108## Network Requirements
109 
110### Firewall Rules
111Allow outbound UDP/TCP to:
112- `*.cloudflare.com` ports 443, 80
113- UDP ports 1024-65535 (WebRTC media)
114 
115### TURN Service
116Enable for users behind restrictive firewalls/proxies:
117```jsonc
118// wrangler.jsonc
119{
120  "vars": {
121    "TURN_SERVICE_ID": "your_turn_service_id"
122  }
123  // Set secret: wrangler secret put TURN_SERVICE_TOKEN
124}
125```
126 
127TURN automatically configured in SDK when enabled in account.
128 
129## Debugging Tips
130 
131```typescript
132// Check devices
133const devices = await meeting.self.getAllDevices();
134meeting.self.on('deviceListUpdate', ({ added, removed, devices }) => console.log('Devices:', { added, removed, devices }));
135 
136// Monitor participants
137meeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined:`, { id: p.id, userId: p.userId, audioEnabled: p.audioEnabled, videoEnabled: p.videoEnabled }));
138 
139// Check room state
140meeting.self.on('roomJoined', () => console.log('Room:', { meetingId: meeting.meta.meetingId, meetingTitle: meeting.meta.meetingTitle, participantCount: meeting.participants.joined.size() + 1, audioEnabled: meeting.self.audioEnabled, videoEnabled: meeting.self.videoEnabled }));
141 
142// Log all events
143['roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'].forEach(event => meeting.self.on(event, (data) => console.log(`[self] ${event}:`, data)));
144['participantJoined', 'participantLeft'].forEach(event => meeting.participants.joined.on(event, (data) => console.log(`[participants] ${event}:`, data)));
145meeting.chat.on('chatUpdate', (data) => console.log('[chat] chatUpdate:', data));
146```
147 
148## Security & Performance
149 
150### Security: Do NOT
151- Expose `CLOUDFLARE_API_TOKEN` in client code, hardcode credentials in frontend
152- Reuse participant tokens, store tokens in localStorage without encryption
153- Allow client-side meeting creation
154 
155### Security: DO
156- Generate tokens server-side only, use HTTPS, implement rate limiting
157- Validate user auth before generating tokens, use `custom_participant_id` to map to your user system
158- Set appropriate preset permissions per user role, rotate API tokens regularly
159 
160### Performance
161- **CPU**: Lower video resolution/frameRate, disable video for audio-only, use `meeting.participants.active` for large meetings, implement virtual scrolling
162- **Bandwidth**: Set max resolution in `mediaConfiguration`, disable screenshare audio if unneeded, use audio-only mode, implement adaptive bitrate
163- **Memory**: Clean up event listeners on unmount, call `meeting.leave()` when done, don't store large participant arrays
164 
165## In This Reference
166- [README.md](README.md) - Overview, core concepts, quick start
167- [configuration.md](configuration.md) - SDK config, presets, wrangler setup
168- [api.md](api.md) - Client SDK APIs, REST endpoints
169- [patterns.md](patterns.md) - Common patterns, React hooks, backend integration
170