Troubleshooting

Common issues and solutions for CometChat iOS UI Kit

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

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
Repo clone failures	Clean repos with commands below, then retry
Build errors after pod install	Open .xcworkspace file, not .xcodeproj

Clean and Retry

rm -rf Pods Podfile.lock
pod cache clean --all
pod install --repo-update

Reset CocoaPods Completely

If repo errors persist:

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:

<!-- 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

Sample App

Complete implementation example

UIKit Source

CometChat UIKit iOS repository

Error Guide

Complete list of error codes

Support

Contact CometChat support