> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.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>


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