> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Troubleshoot CometChat Calls SDK v5 on React Native for setup, authentication, permissions, call launch, media, and session issues.

## 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 |
| Call fails to connect after rendering `<CometChatCalls.Component>` | Invalid or expired `callToken` | Generate a fresh token with `generateToken()` and pass it as the `callToken` prop. There is no `joinSession()` method in React Native — you join by rendering the component |

***

## 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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.