> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> CometChat Calling SDK v5 - Troubleshooting for Flutter

## 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](https://app.cometchat.com/) |
| 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](https://app.cometchat.com/) or [REST API](/rest-api/users/create) 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](/calls/flutter/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](/calls/flutter/voip-calling) |
| Background call drops      | OS kills the app                         | See [Background Handling](/calls/flutter/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](/calls/flutter/picture-in-picture) |