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

# Troubleshooting

> Troubleshoot CometChat iOS UI Kit setup, CocoaPods, Swift Package Manager, initialization, theming, permissions, and real-time updates.

<Accordion title="AI Integration Quick Reference">
  | Field         | Value                                                             |
  | ------------- | ----------------------------------------------------------------- |
  | Platform      | iOS UI Kit                                                        |
  | Common Issues | Initialization, theming, real-time updates, permissions           |
  | Key Checks    | CometChatUIKit.init(uiKitSettings:), user login, init/login order |
  | Permissions   | Camera, microphone, photo library (Info.plist)                    |
  | Debug         | Check SDK connection status, verify dashboard settings            |
</Accordion>

This guide covers common issues and solutions when working with the CometChat iOS UI Kit.

***

## CocoaPods Issues

| Issue                                | Solution                                                                                 |
| ------------------------------------ | ---------------------------------------------------------------------------------------- |
| "Could not find compatible versions" | Run `pod install --repo-update` to refresh spec repos                                    |
| Pod version not found                | Verify the version exists on [CocoaPods](https://cocoapods.org/pods/CometChatUIKitSwift) |
| Repo clone failures                  | Clean repos with commands below, then retry                                              |
| Build errors after pod install       | Open `.xcworkspace` file, not `.xcodeproj`                                               |

### Clean and Retry

```bash theme={null}
rm -rf Pods Podfile.lock
pod cache clean --all
pod install --repo-update
```

### Reset CocoaPods Completely

If repo errors persist:

```bash theme={null}
rm -rf ~/.cocoapods/repos
pod setup
pod install --repo-update
```

### Fallback to Swift Package Manager

If CocoaPods continues to fail, use SPM instead:

1. Remove Podfile and Pods folder
2. Open your `.xcodeproj` in Xcode
3. Go to **File → Add Package Dependencies**
4. Add `https://github.com/cometchat/cometchat-uikit-ios` with version `5.1.9`
5. Add `https://github.com/cometchat/chat-sdk-ios` with version `4.1.0`

***

## Initialization Issues

| Issue                  | Solution                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| SDK not initialized    | Call `CometChatUIKit.init(uiKitSettings:)` before any UI Kit operations                          |
| User not logged in     | Ensure `CometChatUIKit.login(uid:)` completes successfully before showing UI                     |
| Init/login order wrong | `init()` must complete before `login()`, and `login()` must complete before rendering components |
| Credentials invalid    | Verify App ID, Auth Key, and Region in CometChat Dashboard                                       |

***

## Theming & Styling

| Issue                     | Solution                                                   |
| ------------------------- | ---------------------------------------------------------- |
| Colors not applying       | Apply theme before `CometChatUIKit.init()`                 |
| Dark mode not working     | Use `UIColor { traitCollection in }` for dynamic colors    |
| Inconsistent colors       | Set all related colors (text, background, border) together |
| Styles not applying       | Apply global styles before `CometChatUIKit.init()`         |
| Instance style overridden | Instance styles take precedence over global styles         |
| Font not loading          | Verify font name is correct and font is added to project   |

***

## Conversations

| Issue                        | Solution                                                                    |
| ---------------------------- | --------------------------------------------------------------------------- |
| Empty conversation list      | Ensure user is logged in and has existing conversations                     |
| Conversations not updating   | Check SDK connection and real-time listeners                                |
| Navigation not working       | Verify `navigationController` is not nil; embed in `UINavigationController` |
| Custom views not appearing   | Ensure custom view has proper constraints and non-zero frame                |
| Typing indicator not showing | Verify `disableTyping` is not set to true                                   |

***

## Users

| Issue                           | Solution                                        |
| ------------------------------- | ----------------------------------------------- |
| Empty user list                 | Ensure SDK is initialized and user is logged in |
| Users not updating in real-time | Check SDK connection and presence listeners     |
| Search not working              | Verify `hideSearch` is not set to true          |
| Status not showing              | Check that `hideUserStatus` is not set to true  |
| Custom views not appearing      | Ensure custom view has proper constraints       |

***

## Groups

| Issue                            | Solution                                        |
| -------------------------------- | ----------------------------------------------- |
| Empty group list                 | Ensure SDK is initialized and user is logged in |
| Groups not updating in real-time | Check SDK connection and group listeners        |
| Search not working               | Verify `hideSearch` is not set to true          |
| Group type icons not showing     | Check that `hideGroupType` is not set to true   |
| Custom views not appearing       | Ensure custom view has proper constraints       |

***

## Group Members

| Issue                          | Solution                                                 |
| ------------------------------ | -------------------------------------------------------- |
| Empty member list              | Ensure group object is valid and has members             |
| Management options not showing | Check logged-in user's permissions (must be admin/owner) |
| Search not working             | Verify `hideSearch` is not set to true                   |
| Status not showing             | Check that `hideUserStatus` is not set to true           |
| Custom views not appearing     | Ensure custom view has proper constraints                |

***

## Message Header

| Issue                        | Solution                                                             |
| ---------------------------- | -------------------------------------------------------------------- |
| Header not showing user info | Ensure user or group is set on the header                            |
| Status not updating          | Check SDK connection and user presence listeners                     |
| Back button not working      | Verify `onBack` callback is set and `hideBackButton` is false        |
| Typing indicator not showing | Ensure typing events are enabled in SDK                              |
| Call buttons not appearing   | Check that `hideVideoCallButton` and `hideVoiceCallButton` are false |

***

## Message List

| Issue                         | Solution                                                     |
| ----------------------------- | ------------------------------------------------------------ |
| Messages not loading          | Ensure user/group is set and SDK is initialized              |
| Real-time updates not working | Check SDK connection status and listeners                    |
| Reactions not showing         | Verify reactions are enabled in dashboard                    |
| Thread replies not working    | Ensure `hideReplyInThreadOption` is not set to true          |
| Custom views not appearing    | Ensure custom view has proper constraints and non-zero frame |
| Scroll position issues        | Check `scrollToBottomOnNewMessages` setting                  |

***

## Message Composer

| Issue                       | Solution                                                |
| --------------------------- | ------------------------------------------------------- |
| Send button not working     | Ensure user or group is set on the composer             |
| Attachments not showing     | Check that attachment options are not hidden            |
| Voice recording not working | Verify microphone permissions are granted in Info.plist |
| Mentions not working        | Ensure `disableMentions` is not set to true             |
| Typing indicators not sent  | Check that `disableTypingEvents` is not set to true     |

***

## Calling

| Issue                     | Solution                                                       |
| ------------------------- | -------------------------------------------------------------- |
| Call buttons not showing  | Verify `CometChatCallsSDK` is in Podfile and run `pod install` |
| "Permission denied" error | Add camera/microphone permissions to Info.plist                |
| Calls not connecting      | Check network connection and CometChat credentials             |
| No incoming call UI       | Verify `CometChatCallsSDK` is installed and user is logged in  |
| Audio not working         | Check device is not on silent mode                             |

***

## AI Features

| Issue                             | Solution                                           |
| --------------------------------- | -------------------------------------------------- |
| AI features not appearing         | Enable them in CometChat Dashboard → AI            |
| Conversation starters not showing | Only appear for new conversations with no messages |
| Smart replies not appearing       | Ensure feature is enabled and messages exist       |
| Summary not generating            | Need sufficient messages in conversation           |
| AI Assistant empty                | Verify user has AI chat history                    |
| Only loading indicator shows      | Set `user` or `group` property                     |
| Styling not applied               | Apply style before presenting view                 |
| Callbacks not firing              | Set callbacks before pushing to navigation         |
| AI not responding                 | Verify AI features are enabled in dashboard        |
| Streaming not working             | Check network connectivity                         |
| Agent not detected                | Verify user has `isAgentic` property set to true   |

***

## Events

| Issue                 | Solution                                                           |
| --------------------- | ------------------------------------------------------------------ |
| Events not firing     | Verify listener is added before the action occurs                  |
| Duplicate events      | Check you're not adding the same listener multiple times           |
| Memory leaks          | Ensure `removeListener` is called in `viewWillDisappear`           |
| UI not updating       | Dispatch UI updates to main thread with `DispatchQueue.main.async` |
| Listener ID conflicts | Use unique, descriptive IDs for each listener                      |

***

## Permissions (Info.plist)

Add these keys to your `Info.plist` for full functionality:

```xml theme={null}
<!-- Camera access for video calls and image capture -->
<key>NSCameraUsageDescription</key>
<string>Camera access is required for video calls and capturing photos</string>

<!-- Microphone access for voice/video calls and audio messages -->
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for voice calls and audio messages</string>

<!-- Photo library access for sending images -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required to send images</string>

<!-- Photo library save access -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow saving photos and videos to your device's photo library</string>
```

***

## Debug Checklist

When troubleshooting issues, verify the following:

1. **SDK Initialization**
   * `CometChatUIKit.init(uiKitSettings:)` called with correct App ID, Region, and Auth Key
   * Init must complete before calling `login()`

2. **User Authentication**
   * User is logged in via `CometChatUIKit.login(uid:)`
   * Auth token is valid and not expired (if using `loginWithAuthToken()`)

3. **Dashboard Settings**
   * Features are enabled (AI, Reactions, etc.)
   * API keys have correct permissions

4. **Network**
   * Device has internet connectivity
   * WebSocket connection is established

5. **Permissions**
   * Required permissions added to Info.plist
   * User has granted permissions at runtime

***

## Getting Help

<CardGroup cols={2}>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Complete implementation example
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5">
    CometChat UIKit iOS repository
  </Card>

  <Card title="Error Guide" href="/articles/error-guide">
    Complete list of error codes
  </Card>

  <Card title="Support" href="https://help.cometchat.com">
    Contact CometChat support
  </Card>
</CardGroup>