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

## Installation & Setup

| Symptom                     | Cause                                           | Fix                                                                                  |
| --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
| `pod install` fails         | CocoaPods version too old or spec repo outdated | Run `pod repo update` and ensure CocoaPods 1.10+                                     |
| 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](https://app.cometchat.com/)  |
| 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](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 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 | Audio session category misconfigured                 | Ensure `AVAudioSession` category is set to `.playAndRecord` with `.defaultToSpeaker` |
| 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                                                                                                            |
| ------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| VoIP push notifications not received  | Missing VoIP certificate or entitlement | Enable Push Notifications and Voice over IP in Xcode capabilities. See [VoIP Calling](/calls/ios/voip-calling) |
| CallKit UI not showing                | CallKit not configured                  | Implement `CXProvider` delegate and report incoming calls. See [VoIP Calling](/calls/ios/voip-calling)         |
| Call drops when app enters background | Background mode not enabled             | Enable "Audio, AirPlay, and Picture in Picture" and "Voice over IP" background modes                           |