Troubleshooting - CometChat Docs

Installation & Setup

Symptom	Cause	Fix
`pod install` can’t find `CometChatCallsSDK` 5.1 or the Push Notifications SDK 2.0	They are not published as pods	Add them with Swift Package Manager. See Setup
SPM resolution fails	Incorrect package URL or version	Verify the package URL and version in Xcode’s package dependencies
`init()` fails silently	Invalid App ID or Region	Double-check credentials from the CometChat Dashboard
App crashes with `-[AppDelegate window]: unrecognized selector` when a call starts	Scene-based app with no `window` property on the `AppDelegate`	Add `var window: UIWindow?` to your `AppDelegate`. See Setup
Linker errors after install	Missing frameworks	Ensure `CometChatCallsSDK` is added to “Frameworks, Libraries, and Embedded Content”

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 call `init()` and wait for completion 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 via `AVCaptureDevice.requestAccess`
`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	The app configures or activates `AVAudioSession` itself, or sets `CometChatAudioSession.callKitAudioEnabled`	Remove your own `setCategory` and `setActive` calls: the Calls SDK configures the audio session. With the Push Notifications SDK’s Calls product linked, CallKit owns it for calls on CallKit and the Push SDK manages `callKitAudioEnabled`; don’t set it yourself
Camera not working	Missing `NSCameraUsageDescription` in Info.plist	Add camera usage description to your `Info.plist`
Microphone not working	Missing `NSMicrophoneUsageDescription` in Info.plist	Add microphone usage description to your `Info.plist`

CallKit & VoIP

Symptom	Cause	Fix
Incoming calls do not ring	Push Notifications SDK Calls product not linked, Push Notifications capability or Voice over IP background mode missing, or no provider ID	Add `CometChatPushNotificationsCalls`, enable the capability and background mode, set `providerId`, and run `ensureRingReady`. See Push Ringing
A killed app does not ring, a running one does	`CometChatPushNotifications.shared.initialize(config:)` runs after launch	Call it from `application(_:didFinishLaunchingWithOptions:)`: iOS only delivers the VoIP push that launched the app when the PushKit registry exists by the end of launch
A killed app does not ring, and the dashboard push log shows APNs `400`	The APNs provider’s environment does not match the build, or its Bundle ID is not the app’s	Turn Enable Production Mode off for builds run from Xcode and on for TestFlight and App Store builds; set the provider’s Bundle ID to the app’s. See Push Ringing → Check the push itself
Answer does nothing / CallKit ends the call	`presentCall(_:)` returned `false`, or the push delegate was released	Keep a strong reference to the delegate (the Push SDK holds it weakly) and present your screen and join from `presentCall(_:)`
Caller never sees “Ringing…” / answered	Caller joined right after `initiateCall`, or registered listeners through `getActiveSession()` before the session existed	Stay on the prepared session, register on `CallSession.shared`, and join on `onParticipantJoined`. See Ringing
Audio call opens the camera	Session type not set at `initiateCall`	Pass `sessionSettings` with `.setSessionType(.voice)` in `InitiateCallOptions`
One-way audio after a lock-screen answer	The app activates `AVAudioSession` itself	Remove your own `setActive(true)` calls: CallKit owns the call’s audio session
Caller keeps ringing when the callee’s phone is off	Nothing ends a ring the callee never received for 5 minutes	Run a 45 s timer on the caller and end the call with `EndCallStatus.unanswered`
Ring keeps playing after logout	Only the Chat SDK was logged out, and the Push SDK’s Chat product is not linked	Call `CometChatCalls.logout` too, after awaiting `unregisterTokens`
Call drops when app enters background	Background mode not enabled	Enable “Audio, AirPlay, and Picture in Picture” and “Voice over IP” background modes