Troubleshooting - CometChat Docs

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
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 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 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 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 for complete setup
Background call drops on Android	App killed by OS in background	See 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

Ringing

Symptom	Cause	Fix
Nothing rings in any app state	`@cometchat/push-notifications-voip-react-native` not installed, or `CometChatVoipNotifications.init()` never called	Install it and initialise it; `getDiagnostics()` reports `voip: false` when it is missing
Rings in the foreground only	The app awaited something before `init()`, so the cold-launch ring window was spent	Make `CometChatVoipNotifications.init()` the first `await` in your entry point
Caller never shows “Ringing…”	The caller joined right after `initiateCall` instead of listening on the prepared session, or the call was delivered over the websocket rather than by push	Listen for `onParticipantConnected` on `getActiveSession()` before joining
Chat options silently lost after adding calling	A config was passed to `CometChatVoipNotifications.init()` in an app that also calls the core `init`	Pass the config to the core only; call the VoIP `init()` with no arguments
Incoming calls stop after switching users	The ring identity is stale	Check `hasLoggedInUid` in diagnostics; log out through the Calls SDK or call `clearIdentity()`
Answering a second call never connects	The new session was prepared before the live one was released	The Push SDK handles this; if you join yourself, wait for `leave()` to settle first
iOS: the app dies mid-ring	`NSMicrophoneUsageDescription` is missing	Declare it; check the device crash reports before assuming a ring-timeout bug
Two ringtones or two screens	Legacy app-side ringing still in place	Remove the `CallListener` ring path — see Migrating from Legacy Ringing