cometchat-ios-troubleshooting

name	cometchat-ios-troubleshooting
description	Diagnose and fix common CometChat iOS integration issues — build errors, runtime errors, and debugging techniques.
license	MIT
compatibility	CometChatUIKitSwift ^5; iOS 13+
metadata	{"author":"CometChat","version":"3.0.0","tags":"chat cometchat ios troubleshooting debugging errors fixes"}

Ground truth: CometChatUIKitSwift ~> 5 (+ CometChatCallsSDK ~> 5) — Pods/SPM .swiftinterface + ui-kit/ios. Official docs: https://www.cometchat.com/docs/ui-kit/ios/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

Purpose

This skill helps diagnose and fix common issues when integrating CometChat iOS UI Kit. It covers build errors, runtime errors, and debugging techniques.

---

1. Build Errors

"No such module 'CometChatUIKitSwift'"

Cause: SDK not installed or not linked properly.

Solutions:

CocoaPods:

# Clean and reinstall
cd /path/to/your/project
rm -rf Pods Podfile.lock
pod install --repo-update

# Open workspace (not project!)
open YourApp.xcworkspace

Swift Package Manager:

1. In Xcode, go to File → Packages → Reset Package Caches
2. File → Packages → Resolve Package Versions
3. Clean build folder: Cmd + Shift + K
4. Build again

Check Podfile:

platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'CometChatUIKitSwift', '~> 5.1'
end

---

"No such module 'CometChatSDK'"

Cause: Core SDK not installed alongside UI Kit.

Solution: The UI Kit should include the SDK automatically. If not:

# Podfile
pod 'CometChatUIKitSwift', '~> 5.1'
pod 'CometChatSDK', '~> 4.0'  # Add explicitly if needed

---

"No such module 'CometChatCallsSDK'"

Cause: Calls SDK not installed but code references it.

Solutions:

1. If you need calls:

# Podfile
pod 'CometChatCallsSDK', '~> 5.0'

2. If you don't need calls: Wrap call-related code in conditional compilation:

#if canImport(CometChatCallsSDK)
import CometChatCallsSDK
// Call-related code here
#endif

---

"Value of type 'CometChatException' has no member 'localizedDescription'"

Cause: Using wrong property for error description.

Solution: Use errorDescription instead of localizedDescription:

case .onError(let error):
    print(error.errorDescription)
    print(error.errorCode)

CometChatException has:

• errorDescription — human-readable error message
• errorCode — error code string
• details — optional dictionary with additional info

---

"'CometChatException' is not convertible to 'any Error'"

Cause: Trying to use CometChatException with Swift's Result<T, Error> type.

Solution: CometChatException does NOT conform to Swift's Error protocol. Don't use Result<T, Error> with CometChat callbacks. Instead, use direct callbacks:

// tier2-expect-error — this block intentionally demonstrates the compile error below
// ❌ WRONG - Don't use Result<T, Error>
func login(completion: @escaping (Result<User, Error>) -> Void) {
    CometChatUIKit.login(uid: uid) { result in
        switch result {
        case .success(let user):
            completion(.success(user))
        case .onError(let error):
            completion(.failure(error))  // ERROR: CometChatException is not Error
        }
    }
}

// ✅ CORRECT - Use CometChatException directly
func login(completion: @escaping (User?, CometChatException?) -> Void) {
    CometChatUIKit.login(uid: uid) { result in
        switch result {
        case .success(let user):
            completion(user, nil)
        case .onError(let error):
            completion(nil, error)
        @unknown default:
            completion(nil, nil)
        }
    }
}

---

"Cannot find 'CometChatConversationsWithMessages' in scope" or "Cannot find 'CometChatMessages' in scope"

Cause: Neither class exists in the kit. They look like "pre-built composite UIViewControllers" but are NOT exported from CometChatUIKitSwift. Older docs and AI-generated guides sometimes claim they exist.

Solution: Compose your own MessagesVC from the real building blocks (CometChatMessageHeader + CometChatMessageList + CometChatMessageComposer). The pattern is the same one the kit's sample app uses (SampleApp/View Controllers/CometChat Components/MessagesVC.swift).

import CometChatUIKitSwift
import CometChatSDK

let conversations = CometChatConversations()
let navController = UINavigationController(rootViewController: conversations)

conversations.set(onItemClick: { [weak navController] conversation, _ in
    let messagesVC = MessagesVC()  // your own VC composing CometChatMessageHeader + List + Composer
    if let group = conversation.conversationWith as? Group {
        messagesVC.set(group: group)
    } else if let user = conversation.conversationWith as? User {
        messagesVC.set(user: user)
    }
    navController?.pushViewController(messagesVC, animated: true)
})

See cometchat-ios-components § 13 ("Custom MessagesVC Implementation") for the full MessagesVC source.

---

"Cannot find 'CometChatCallLogs' in scope"

Cause: CometChatCallLogs requires CometChatCallsSDK which is not installed.

Solutions:

1. Install the Calls SDK:

# Podfile
pod 'CometChatCallsSDK', '~> 5.0'

2. Or wrap in conditional compilation:

#if canImport(CometChatCallsSDK)
let callLogs = CometChatCallLogs()
#else
// Show placeholder or hide calls tab
#endif

---

"Duplicate symbols" or "Multiple commands produce"

Cause: Conflicting dependencies or duplicate frameworks.

Solutions:

1. Clean derived data:

rm -rf ~/Library/Developer/Xcode/DerivedData

2. Check for duplicate pods:

pod deintegrate
pod install

3. Check Build Phases:
   • Go to Target → Build Phases → Link Binary With Libraries
   • Remove any duplicate frameworks

---

"The iOS deployment target is set to X.X, but the range of supported deployment target versions is Y.Y to Z.Z"

Cause: Minimum iOS version mismatch.

Solution:

1. Update your project's deployment target to iOS 13.0 or higher
2. Update Podfile:

platform :ios, '13.0'

3. Run:

pod install

---

"Sandbox: rsync.samba denied"

Cause: Xcode sandbox permission issue (common in Xcode 15+).

Solution:

1. Disable User Script Sandboxing in Build Settings:

   • Select your app target
   • Go to Build Settings
   • Search for "User Script Sandboxing"
   • Set ENABLE_USER_SCRIPT_SANDBOXING to No

2. Or add to your Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
    end
  end
end

3. Then run:

pod install

4. Clean and rebuild:

rm -rf ~/Library/Developer/Xcode/DerivedData

---

"Framework not found" during archive

Cause: Framework search paths issue.

Solution:

1. Go to Target → Build Settings
2. Search for "Framework Search Paths"
3. Add: $(inherited) and $(PROJECT_DIR)/Pods
4. Set "Build Active Architecture Only" to No for Release

---

2. Runtime Errors

"CometChat is not initialized"

Cause: Trying to use CometChat before initialization completes.

Solution:

// ❌ Wrong - using before init completes
CometChatUIKit(uiKitSettings: settings) { _ in }
let conversations = CometChatConversations()  // Too early!

// ✅ Correct - wait for completion
CometChatUIKit(uiKitSettings: settings) { result in
    switch result {
    case .success:
        DispatchQueue.main.async {
            let conversations = CometChatConversations()
            // Now safe to use
        }
    case .failure(let error):
        print("Init failed: \(error)")
    }
}

---

"Invalid App ID" or "App not found"

Cause: Wrong App ID or region.

Solutions:

1. Verify App ID in CometChat Dashboard
2. Check region matches (us, eu, or in)
3. Ensure no extra spaces in credentials

let uiKitSettings = UIKitSettings()
    .set(appID: "YOUR_APP_ID")  // No spaces!
    .set(region: "us")           // Lowercase
    .build()

---

"Invalid Auth Key"

Cause: Wrong or expired Auth Key.

Solutions:

1. Get fresh Auth Key from Dashboard → API & Auth Keys
2. Use the correct key type (Auth Key, not REST API Key)
3. Check for copy/paste errors

---

"User not found" or "UID not found"

Cause: Trying to login with a UID that doesn't exist.

Solutions:

1. Use pre-created test users:

   • cometchat-uid-1 through cometchat-uid-5

2. Create user first:

let user = User(uid: "new-user-123", name: "John Doe")
CometChatUIKit.create(user: user) { result in
    switch result {
    case .success(let user):
        // Now login
        CometChatUIKit.login(uid: user.uid ?? "") { _ in }
    case .onError(let error):
        print("Create failed: \(error)")
    }
}

---

"Already logged in"

Cause: Calling login when user is already logged in.

Solution:

// Check for existing session first
if let currentUser = CometChatUIKit.getLoggedInUser() {
    print("Already logged in as: \(currentUser.name ?? "")")
    // Proceed to chat UI
} else {
    // Login
    CometChatUIKit.login(uid: "user-123") { _ in }
}

---

Blank/Empty Conversation List

Cause: No conversations exist for the logged-in user.

Solutions:

1. Send a test message:

   • Go to CometChat Dashboard → Users
   • Select another user
   • Send a message to your logged-in user

2. Check user is logged in:

if let user = CometChatUIKit.getLoggedInUser() {
    print("Logged in as: \(user.uid ?? "")")
} else {
    print("Not logged in!")
}

3. Check for errors:

let conversations = CometChatConversations()
conversations.set(onError: { error in
    print("Error loading conversations: \(error.errorDescription ?? "")")
})
conversations.set(onEmpty: {
    print("No conversations found")
})

---

Messages Not Sending

Cause: Various issues with message sending.

Solutions:

1. Check user/group is set:

let composer = CometChatMessageComposer()
composer.set(user: user)  // Must be set!

2. Check for errors:

composer.set(onError: { error in
    print("Composer error: \((error as? CometChatException)?.errorDescription ?? "")")
})

3. Verify network connection:

import Network

let monitor = NWPathMonitor()
monitor.pathUpdateHandler = { path in
    if path.status == .satisfied {
        print("Connected")
    } else {
        print("No connection")
    }
}
monitor.start(queue: DispatchQueue.global())

---

Push Notifications Not Working

Cause: Multiple possible issues.

Checklist:

1. Physical device? Push doesn't work on simulator

2. Permissions granted?

UNUserNotificationCenter.current().getNotificationSettings { settings in
    print("Authorization status: \(settings.authorizationStatus.rawValue)")
}

3. Token registered?

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
    print("APNs Token: \(token)")
    
    // Register with CometChat
    CometChat.registerTokenForPushNotification(token: token, settings: ["voip": false]) { success in
        print("Token registered: \(success)")
    } onError: { error in
        print("Token registration failed: \(error?.errorDescription ?? "")")
    }
}

4. Certificate uploaded? Check Dashboard → Notifications → Push Notifications

5. Correct environment? Development vs Production certificate must match

---

Calls Not Working

Cause: Missing SDK or permissions.

Checklist:

1. CometChatCallsSDK installed?

pod 'CometChatCallsSDK', '~> 5.0'

2. Permissions in Info.plist?

<key>NSCameraUsageDescription</key>
<string>Camera access for video calls</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access for calls</string>

3. Background modes enabled?

   • Audio, AirPlay, and Picture in Picture
   • Voice over IP

4. Testing on real device? Calls don't work on simulator

5. Did you call CometChatCalls.login(...)? ⚠️ On iOS there is NO CometChatCalls.login — the iOS CometChatCallsSDK has no login/joinSession/SessionSettingsBuilder. The authority is the vendored CometChatCallsSDK.swiftinterface (generateToken / startSession / CallSettingsBuilder / CallsEventsDelegate). The calls-sdk-ios repo's own skills/ describe a different API and will mislead you — don't follow them. Default calling works through the UI Kit (CometChatUIKit calling-enabled) without a separate calls login; for custom calling, use generateToken → startSession.

Background push for calls not arriving (Privacy manifest / APNs vs FCM)

Cause: Missing privacy manifest, or an APNs-vs-FCM provider mismatch.

Fix:

• Add a PrivacyInfo.xcprivacy privacy manifest to the app target (required by App Store review; its absence can also break some push/SDK behaviors).
• Match the provider to your token type: if you registered an APNs device/VoIP token, the dashboard provider must be APNs (.p8 + Team ID + Key ID, dev-vs-prod environment matching the build); if you route iOS through FCM, register with the FCM provider and the FCM_IOS platform. A token registered against the wrong provider silently never delivers. See cometchat-ios-push.

---

Memory Warnings / Crashes

Cause: Memory leaks or retain cycles.

Solutions:

1. Use weak references in closures:

conversations.set(onItemClick: { [weak self] conversation, _ in
    self?.openMessages(for: conversation)
})

2. Remove listeners when done:

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    CometChatMessageEvents.removeListener("my-listener")
}

3. Profile with Instruments:
   • Product → Profile → Leaks
   • Look for CometChat-related leaks

---

UI Not Updating

Cause: Updates happening on background thread.

Solution:

// Always update UI on main thread
CometChatUIKit.login(uid: "user-123") { result in
    DispatchQueue.main.async {
        switch result {
        case .success:
            self.showConversations()
        case .onError(let error):
            self.showError(error)
        }
    }
}

---

3. Debugging Techniques

Inspect SDK errors

The CometChat iOS SDK has no public log-level API (there is no CometChat.setLogLevel / AppSettingsBuilder logging toggle). Diagnose by reading the CometChatException handed to each call's onError closure:

CometChat.init(appId: appID, appSettings: settings, onSuccess: { _ in
    print("CometChat init OK")
}, onError: { error in
    // CometChatException → code + message (init's onError is non-optional)
    print("init failed:", error.errorCode, error.errorDescription)
})

Check Connection Status

CometChat.addConnectionListener("debug-listener", self)

extension YourClass: CometChatConnectionDelegate {
    func connected() {
        print("✅ CometChat connected")
    }
    
    func connecting() {
        print("🔄 CometChat connecting...")
    }
    
    func disconnected() {
        print("❌ CometChat disconnected")
    }
}

Monitor Message Events

class DebugMessageListener: CometChatMessageDelegate {
    
    func onTextMessageReceived(textMessage: TextMessage) {
        print("📩 Text message received: \(textMessage.text ?? "")")
    }
    
    func onMediaMessageReceived(mediaMessage: MediaMessage) {
        print("📎 Media message received: \(mediaMessage.messageType)")
    }
    
    func onMessageDeleted(message: BaseMessage) {
        print("🗑 Message deleted: \(message.id)")
    }
}

CometChat.addMessageListener("debug-messages", DebugMessageListener())

Network Debugging

Use Charles Proxy or Proxyman to inspect CometChat API calls:

1. Install Charles Proxy
2. Enable SSL Proxying for *.cometchat.io
3. Install Charles certificate on device/simulator
4. Monitor requests and responses

Xcode Debugging

Breakpoints:

• Set breakpoints in CometChat callbacks
• Use symbolic breakpoints for CometChat methods

Console:

// Print current state
print("User: \(CometChatUIKit.getLoggedInUser()?.uid ?? "none")")
print("Logged in: \(CometChatUIKit.getLoggedInUser() != nil)")

---

4. Common Error Codes

Code	Description	Solution
ERR_UID_NOT_FOUND	User doesn't exist	Create user first
ERR_ALREADY_LOGGED_IN	User already logged in	Check session before login
ERR_NOT_LOGGED_IN	No active session	Login first
AUTH_ERR_AUTH_TOKEN_NOT_FOUND	Invalid auth token	Generate new token
ERR_INVALID_APP_ID	Wrong App ID	Verify in dashboard
ERR_INVALID_API_KEY	Wrong API/Auth Key	Get correct key from dashboard
ERR_BLOCKED_BY_EXTENSION	Blocked by extension	Check extension settings
ERR_RATE_LIMIT_EXCEEDED	Too many requests	Implement rate limiting
ERR_WEBSOCKET_CONNECTION_FAILED	Connection failed	Check network, retry

---

5. Performance Issues

Slow Conversation Loading

Solutions:

1. Limit initial fetch:

let conversations = CometChatConversations()
conversations.set(conversationsRequestBuilder: ConversationRequest.ConversationRequestBuilder()
    .set(limit: 20)  // Reduce initial load
)

2. Enable pagination: Conversations automatically paginate. Ensure you're not fetching all at once.

Slow Message Loading

Solutions:

1. Limit message fetch:

let messageList = CometChatMessageList()
messageList.set(messagesRequestBuilder: MessagesRequest.MessageRequestBuilder()
    .set(uid: user.uid ?? "")
    .set(limit: 30)  // Reduce initial load
)

2. Hide unnecessary features:

messageList.hideReceipts = true  // If not needed
messageList.hideAvatar = true    // If not needed

High Memory Usage

Solutions:

1. Release unused view controllers:

// Don't keep strong references to dismissed VCs

2. Clear image cache if needed:

// CometChat handles image caching internally
// But you can clear URLCache if needed
URLCache.shared.removeAllCachedResponses()

---

6. SwiftUI-Specific Issues

View Not Updating

Cause: SwiftUI not detecting state changes.

Solution:

struct ChatView: View {
    @State private var selectedConversation: Conversation?
    
    var body: some View {
        ConversationsWrapper(selectedConversation: $selectedConversation)
            .onChange(of: selectedConversation) { newValue in
                // Handle selection
            }
    }
}

struct ConversationsWrapper: UIViewControllerRepresentable {
    @Binding var selectedConversation: Conversation?
    
    func makeUIViewController(context: Context) -> CometChatConversations {
        let vc = CometChatConversations()
        vc.set(onItemClick: { conversation, _ in
            selectedConversation = conversation
        })
        return vc
    }
    
    func updateUIViewController(_ uiViewController: CometChatConversations, context: Context) {
        // Handle updates if needed
    }
}

Navigation Issues

Cause: Mixing UIKit navigation with SwiftUI.

Solution:

struct ChatNavigationView: View {
    @State private var path = NavigationPath()
    
    var body: some View {
        NavigationStack(path: $path) {
            ConversationsView(onSelect: { conversation in
                path.append(conversation)
            })
            .navigationDestination(for: Conversation.self) { conversation in
                MessagesView(conversation: conversation)
            }
        }
    }
}

---

7. Quick Fixes Checklist

When something isn't working:

1. Clean build: Cmd + Shift + K
2. Delete derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
3. Reinstall pods: pod deintegrate && pod install
4. Check credentials: App ID, Auth Key, Region
5. Check user exists: Use test users or create first
6. Check network: Device has internet connection
7. Check permissions: Camera, microphone, notifications
8. Check main thread: UI updates on main thread
9. Check completion handlers: Wait for async operations
10. Inspect errors: read the CometChatException in each call's onError (errorCode + errorDescription) — the SDK has no log-level toggle

---

8. Theming Errors

"Value of type 'MessageBubbleStyle' has no member 'outgoingBackgroundColor'"

Cause: Incorrect property access for message bubble styles.

Solution: Message bubble styles use separate .incoming and .outgoing style objects, not combined properties:

// ✅ CORRECT - Use separate incoming/outgoing styles
CometChatMessageBubble.style.outgoing.backgroundColor = CometChatTheme.primaryColor
CometChatMessageBubble.style.incoming.backgroundColor = CometChatTheme.neutralColor300

// For text colors within bubbles
CometChatMessageBubble.style.outgoing.textBubbleStyle.textColor = .white
CometChatMessageBubble.style.incoming.textBubbleStyle.textColor = CometChatTheme.textColorPrimary

---

"Value of type 'ConversationsStyle' has no member 'titleColor'"

Cause: Using incorrect property names for component styles.

Solution: Check the actual property names in the style struct:

// ✅ CORRECT ConversationsStyle properties
CometChatConversations.style.listItemTitleTextColor = CometChatTheme.textColorPrimary
CometChatConversations.style.listItemTitleFont = CometChatTypography.Heading4.medium
CometChatConversations.style.listItemSubTitleTextColor = CometChatTheme.textColorSecondary
CometChatConversations.style.listItemSubTitleFont = CometChatTypography.Body.regular

---

"Value of type 'MessageComposerStyle' has no member 'inputBackgroundColor'"

Cause: Using incorrect property names for composer style.

Solution: Use the correct property names:

// ✅ CORRECT MessageComposerStyle properties
CometChatMessageComposer.style.composeBoxBackgroundColor = CometChatTheme.backgroundColor01
CometChatMessageComposer.style.composeBoxBorderColor = CometChatTheme.borderColorDefault
CometChatMessageComposer.style.placeHolderTextColor = CometChatTheme.textColorTertiary
CometChatMessageComposer.style.textFiledColor = CometChatTheme.textColorPrimary
CometChatMessageComposer.style.activeSendButtonImageBackgroundColor = CometChatTheme.primaryColor

---

"Value of type 'BadgeStyle' has no member 'cornerRadius'" (type mismatch)

Cause: BadgeStyle.cornerRadius is CometChatCornerStyle?, not a simple value.

Solution:

// ✅ CORRECT - cornerRadius is optional CometChatCornerStyle
CometChatBadge.style.cornerRadius = CometChatCornerStyle(cornerRadius: 8)
// or nil for default pill shape
CometChatBadge.style.cornerRadius = nil

---

"Cannot assign value of type 'UIColor' to type 'CGColor'"

Cause: BadgeStyle.borderColor is CGColor, not UIColor.

Solution:

// ✅ CORRECT - use .cgColor
CometChatBadge.style.borderColor = UIColor.clear.cgColor
CometChatBadge.style.borderColor = UIColor.white.cgColor

---

Theme Changes Not Applying

Cause: Theme configured after UI is already displayed.

Solution: Configure theme before showing any CometChat UI:

// In AppDelegate or App init, BEFORE showing any CometChat views
func configureTheme() {
    CometChatTheme.primaryColor = UIColor.systemBlue
    CometChatTheme.backgroundColor01 = UIColor.systemBackground
    // ... other theme settings
}

// Call this before CometChatUIKit.init()
configureTheme()

---

"Type 'CometChatSpacing' has no member 'Spacing1'" or similar

Cause: Using incorrect property access for spacing values.

Solution: CometChatSpacing uses nested classes, not direct properties:

// ✅ CORRECT - Use nested class syntax
CometChatSpacing.Spacing.s1 = 4
CometChatSpacing.Spacing.s2 = 8
CometChatSpacing.Padding.p1 = 4
CometChatSpacing.Padding.p2 = 8
CometChatSpacing.Radius.r1 = 4
CometChatSpacing.Radius.r2 = 8
CometChatSpacing.Radius.rMax = 1000
CometChatSpacing.Margin.m1 = 4

---

"Cannot infer type of closure parameter" or "Cannot infer contextual base"

Cause: Missing type annotations in closures for custom views.

Solution: Always provide explicit type annotations for closure parameters:

import CometChatSDK

// ✅ CORRECT - Explicit type annotation
users.set(subtitle: { (user: User?) -> UIView in
    let label = UILabel()
    if user?.status == .online {
        label.text = "Online"
        label.textColor = .systemGreen
    } else {
        label.text = "Offline"
        label.textColor = .gray
    }
    return label
})

Note: Use set(subtitle:) method, not direct property assignment. The User type is from CometChatSDK.

---

"Value of type 'CometChatUsers' has no member 'subtitleView'"

Cause: Using wrong property name.

Solution: CometChatUsers uses subtitle, not subtitleView:

// ✅ CORRECT
users.set(subtitle: { (user: User?) -> UIView in
    // Return custom view
})

// Different components use different names:
// - CometChatUsers: set(subtitle:)
// - CometChatConversations: set(subtitleView:)
// - CometChatMessageHeader: set(subtitleView:)

---

10. Getting Help

CometChat Resources

• Documentation: https://www.cometchat.com/docs/ios-uikit
• GitHub Issues: https://github.com/cometchat/cometchat-uikit-ios/issues
• Support: https://www.cometchat.com/support

Information to Include in Bug Reports

1. CometChatUIKitSwift version
2. iOS version
3. Xcode version
4. Device (simulator or physical)
5. Error message / stack trace
6. Steps to reproduce
7. Relevant code snippets