cometchat-ios-troubleshooting— agent skill

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'

1. 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'

1. 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

1. Check for duplicate pods:

pod deintegrate
pod install

1. 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'

1. 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

1. 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

1. Then run:

pod install

1. 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

1. 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

1. Check user is logged in:

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

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

1. Check for errors:

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

1. 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

1. Permissions granted?

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

1. 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 ?? "")")
    }
}

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

1. Correct environment? Development vs Production certificate must match

Calls Not Working

Cause: Missing SDK or permissions.

Checklist:

1. CometChatCallsSDK installed?

pod 'CometChatCallsSDK', '~> 5.0'

1. Permissions in Info.plist?

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

1. Background modes enabled?

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

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

1. 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)
})

1. Remove listeners when done:

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

1. 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

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
)

1. 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
)

1. 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

1. 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