Installation & Setup
| Symptom | Cause | Fix |
|---|---|---|
pub get fails | Incorrect package name or version | Verify cometchat_calls_sdk is correctly added to pubspec.yaml |
init() fails silently | Invalid App ID or Region | Double-check credentials from the CometChat Dashboard |
| iOS build fails | CocoaPods issue | Run cd ios && pod install --repo-update |
| Android build fails | minSdkVersion too low | Set minSdkVersion to 21 or higher in android/app/build.gradle |
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 using permission_handler package |
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 at OS level | Check app permissions in device settings |
| Black video tiles | Camera permission not granted | Request permissions before joining the session |
Platform-Specific
| Symptom | Cause | Fix |
|---|---|---|
| iOS crash on call join | Missing usage descriptions in Info.plist | Add NSCameraUsageDescription and NSMicrophoneUsageDescription to ios/Runner/Info.plist |
| Android crash on call join | Missing runtime permissions | Request CAMERA and RECORD_AUDIO permissions at runtime |
| VoIP not working on iOS | Missing VoIP entitlement | Enable Push Notifications and Voice over IP capabilities. See VoIP Calling |
| Background call drops | OS kills the app | See Background Handling for platform-specific setup |
Picture-in-Picture
| Symptom | Cause | Fix |
|---|---|---|
| PiP not working on iOS | iOS version below 15 | Ensure iOS 15+ and background mode enabled |
| PiP not working on Android | Missing manifest attribute | Add android:supportsPictureInPicture="true" to activity in AndroidManifest.xml. See PiP |