Installation & Setup
| Symptom | Cause | Fix |
|---|---|---|
CometChatCalls is not defined | SDK not installed or not linked | Run npm install @cometchat/calls-sdk-react-native and rebuild |
init() fails silently | Invalid App ID or Region | Double-check credentials from the CometChat Dashboard |
| Build fails on iOS | CocoaPods not installed or outdated | Run cd ios && pod install after adding the SDK |
| Build fails on Android | Missing native dependencies | Run npx react-native link or rebuild with npx react-native run-android |
Authentication
| Symptom | Cause | Fix |
|---|---|---|
login() fails with invalid UID | UID doesn’t exist in CometChat | Create the user via Dashboard or REST API first |
| Auth token expired | Token has a limited lifetime | Generate a new auth token and call login() again |
login() called before init() | SDK not initialized | Always await CometChatCalls.init() before calling login() |
Joining a Session
| Symptom | Cause | Fix |
|---|---|---|
generateToken() fails | User not logged in or invalid session ID | Ensure login() completes before generating a token |
| Session joins but no audio/video | Permissions not granted | Request camera and microphone permissions before joining. See platform permission guides |
joinSession() throws error | Invalid or expired token | Generate a fresh token using generateToken() before joining |
Audio & Video
| Symptom | Cause | Fix |
|---|---|---|
| No audio from remote participants | Audio routing issue | Check Audio Modes for speaker/earpiece configuration |
| Camera not working | Permission denied or another app using camera | Check app permissions in device settings |
| Black video tiles | Camera permission not granted at OS level | Request permissions using react-native-permissions or similar library |
Platform-Specific
| Symptom | Cause | Fix |
|---|---|---|
| App crashes on iOS when joining call | Missing microphone usage description | Add NSMicrophoneUsageDescription and NSCameraUsageDescription to Info.plist |
| Android build fails with duplicate classes | Conflicting WebRTC dependencies | Exclude duplicate transitive dependencies in build.gradle |
| VoIP push notifications not working on iOS | Missing VoIP certificate or CallKit setup | See VoIP Calling for complete setup |
| Background call drops on Android | App killed by OS in background | See Background Handling for foreground service setup |
Picture-in-Picture
| Symptom | Cause | Fix |
|---|---|---|
| PiP not working on iOS | iOS version below 15 or missing entitlement | Ensure iOS 15+ and PiP background mode is enabled |
| PiP not working on Android | Missing supportsPictureInPicture in manifest | Add PiP activity attribute in AndroidManifest.xml. See PiP |