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 |
pod install stops with “cometchat_calls_sdk builds on iOS with Swift Package Manager only” | Swift Package Manager is off for the app | Run flutter config --enable-swift-package-manager, and remove enable-swift-package-manager: false from your pubspec.yaml if it is set |
| iOS build fails with “Value of type ‘NWPath’ has no member ‘isUltraConstrained‘“ | Building with Xcode older than 26.1.1 (connectivity_plus 7.1+ uses the iOS 26 SDK) | Build with Xcode 26.1.1 or later, or hold connectivity_plus at 7.0.x in your pubspec.yaml |
Android build fails in checkReleaseAarMetadata asking for API 36 | compileSdk below 36 | Set compileSdk to 36 and use Android Gradle Plugin 8.9.1 or later |
| Android build fails | minSdkVersion too low | Set minSdkVersion to 26 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 |
| Incoming calls don’t ring on iOS | Missing VoIP entitlement | Enable Push Notifications and Voice over IP capabilities. See Push Ringing |
| Incoming calls don’t ring on Android | cometchat_voip missing, pushes not handed to it, or the device isn’t ring-ready | Pass every push to CometChatVoip.handlePushNotification with sentTime, from both message handlers, and run checkRingReadiness. See Push Ringing |
| Rings, then the app dies before Answer | Call push sent at normal priority | Send call pushes at high priority |
| Caller never sees “Ringing…” or the answer | Caller joined right after initiateCall | Stay on the prepared session and join on onParticipantJoined. See Ringing |
| Audio call rings as video, or opens the camera | InitiateCallOptions.type or the session type not set; both default to video | Set type, and the type in sessionSettings |
| Calls still ring after logout | The push token wasn’t unregistered | Call CometChatVoip.unregisterPushToken() before CometChatCalls.logout |
| 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 |