> ## 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 React Native

## 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](https://app.cometchat.com/) |
| 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](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 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](/calls/react-native/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](/calls/react-native/voip-calling) for complete setup                         |
| Background call drops on Android           | App killed by OS in background            | See [Background Handling](/calls/react-native/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](/calls/react-native/picture-in-picture) |