Troubleshooting

Common failure modes and fixes for the CometChat Flutter UI Kit.

AI Agent Component Spec

Field	Value
Page type	Troubleshooting reference
Scope	All CometChat Flutter UI Kit v5 issues — initialization, rendering, theming, calling, extensions, AI features, localization, sound, events
When to reference	When a component fails to render, data is missing, styling doesn’t apply, or a feature doesn’t appear

Initialization and Login

Symptom	Cause	Fix
CometChatUIKit.init() fails silently	Invalid App ID, Region, or Auth Key	Double-check credentials from the CometChat Dashboard
Widget doesn’t render	init() not called or not awaited before rendering	Ensure init() completes before mounting widgets. See Methods
Widget renders but shows no data	User not logged in	Call CometChatUIKit.login("UID") after init
Login fails with “UID not found”	UID doesn’t exist in your CometChat app	Create the user via Dashboard, SDK, or API first
Blank screen after login	Widget mounted before init/login completes	Use FutureBuilder or state to conditionally render after login resolves
getLoggedInUser() returns null	User not logged in or session expired	Call login() or loginWithAuthToken() first
sendTextMessage() fails	User not logged in or invalid receiver	Ensure login completes before sending messages
Auth Key exposed in production	Using Auth Key instead of Auth Token	Switch to Auth Token for production

---

Platform-Specific Issues

Android

Symptom	Cause	Fix
App crashes on launch	Missing internet permission	Add <uses-permission android:name="android.permission.INTERNET"/> to AndroidManifest.xml
Network requests fail	Missing network security config	For debug builds, add android:usesCleartextTraffic="true" to AndroidManifest.xml
Camera/microphone not working	Missing permissions	Add camera and microphone permissions to AndroidManifest.xml
Build fails with minSdk error	minSdkVersion too low	Set minSdkVersion 21 or higher in build.gradle
ProGuard issues in release build	Missing ProGuard rules	Add CometChat ProGuard rules to proguard-rules.pro

iOS

Symptom	Cause	Fix
App crashes on camera/mic access	Missing Info.plist entries	Add NSCameraUsageDescription and NSMicrophoneUsageDescription to Info.plist
Build fails with deployment target error	iOS version too low	Set platform :ios, '13.0' or higher in Podfile
Pod install fails	CocoaPods cache issue	Run pod cache clean --all then pod install
Bitcode error	Bitcode enabled	Disable bitcode in Xcode build settings
Simulator crashes	Architecture mismatch	Ensure you’re using the correct simulator architecture

---

Theming and Styling

Symptom	Cause	Fix
Theme not applied	Theme not passed to widget	Wrap your app with CometChatTheme or pass theme to individual widgets
Colors not changing	Using wrong color palette	Use CometChatThemeHelper.getColorPalette(context) to access theme colors
Typography not applied	Font family not set	Set font family in CometChatTypography
Dark mode not working	Theme mode not set	Use ThemeMode.dark and ensure CometChatColorPalette has dark mode colors
Custom style not applying	Style property not set correctly	Check the component’s style class (e.g., CometChatConversationsStyle)
Spacing issues	Using wrong spacing values	Use CometChatSpacing for consistent spacing

---

Components

Symptom	Cause	Fix
Callback not firing	Wrong callback name or signature	Check the Actions section on the component page for exact callback name and parameters
Custom view not appearing	Returning null from view builder	Ensure view builder returns a valid Widget
Messages not loading	Invalid user/group object passed	Ensure you fetch the user/group via SDK before passing to components
List not refreshing	State not updated	Call setState() or use a state management solution
Scroll position lost	Key not set on list items	Ensure unique keys are set on list items
Empty state not showing	emptyStateView not set	Provide an emptyStateView builder

---

Calling

Symptom	Cause	Fix
Call buttons not appearing	Calling extension not installed	Add cometchat_calls_uikit to your pubspec.yaml
Incoming call screen not showing	CometChatIncomingCall not in widget tree	Add CometChatIncomingCall at the app root level
Call fails to connect	WebRTC permissions not granted	Ensure camera and microphone permissions are granted
Audio not working in call	Audio session not configured	Configure audio session for iOS in AppDelegate.swift
Video not showing	Camera permission denied	Request camera permission before starting video call
Call drops immediately	Network connectivity issue	Check internet connection and firewall settings

---

Extensions

Symptom	Cause	Fix
Extension feature not appearing	Extension not activated in Dashboard	Enable the specific extension from your Dashboard
Stickers not showing in composer	Sticker extension not enabled	Activate Sticker Extension in Dashboard
Polls option missing	Polls extension not enabled	Activate Polls Extension in Dashboard
Link preview not rendering	Link Preview extension not enabled	Activate Link Preview Extension in Dashboard
Reactions not working	Reactions extension not enabled	Activate Reactions Extension in Dashboard
Video thumbnails show a grey box (image thumbnails render fine)	The default v4 Chat SDK does not pass the generated thumbnail URL correctly, so it fails to load	Override cometchat_sdk to 5.0.4, see Video thumbnails not rendering below

---

Video thumbnails not rendering

With Flutter UI Kit 5.2.x, the message list resolves the Thumbnail Generation extension’s cometchat_sdk (the v4 Chat SDK) by default. On that version, the generated thumbnail URL is not passed correctly, so video thumbnails fail to load and fall back to a grey box with a play icon.

Image thumbnails are unaffected because they fall back to the full image URL, which is why only videos appear broken.

This is resolved in the v5 Chat SDK. Since the UI Kit still resolves the v4 SDK by default, pin the SDK version using dependency_overrides in your app’s pubspec.yaml:

dependency_overrides:
  cometchat_sdk: 5.0.4

Then reinstall dependencies and do a clean rebuild:

flutter clean
flutter pub get

Use version 5.0.4 specifically. Avoid overriding to the latest v5 SDK, as newer releases include changes that can cause compile-time issues with UI Kit 5.2.x.

---

AI Features

Symptom	Cause	Fix
AI features not appearing	Feature not activated in Dashboard	Enable the specific AI feature from your Dashboard
Conversation Starter not showing	Feature not enabled or no conversation context	Ensure Conversation Starter is activated
Smart Replies not appearing	Feature not enabled in Dashboard	Ensure Smart Replies is activated
AI extension not in UIKitSettings	AI features not configured	Add AI extensions to UIKitSettings.aiFeature list

UIKitSettings uiKitSettings = (UIKitSettingsBuilder()
  ..aiFeature = [
    AISmartRepliesExtension(),
    AIConversationStarterExtension(),
    AIConversationSummaryExtension(),
  ]
).build();

---

Localization

Symptom	Cause	Fix
UI text not translated	Language code not matching	Check supported languages in Localize
Custom translations not appearing	Translations not added correctly	Use Translations class to add custom translations
Date/time format unchanged	Locale not set	Set locale in MaterialApp or use dateTimeFormatterCallback
RTL layout not working	Text direction not set	Set textDirection: TextDirection.rtl for RTL languages

---

Sound

Symptom	Cause	Fix
No sound plays	Sound disabled or volume muted	Check CometChatSoundManager settings and device volume
Custom sound not playing	Invalid file path or format	Ensure the path is correct and file is WAV/MP3 format
Sound plays multiple times	Multiple listeners registered	Ensure you’re not registering duplicate sound listeners
Sound continues after app backgrounded	Sound not stopped	Call CometChatSoundManager.stop() when appropriate

---

Events

Symptom	Cause	Fix
Event listener not firing	Subscribed to wrong event	Check the Events page for exact event names
Duplicate event triggers	Multiple subscriptions	Remove listener in dispose() method
Event fires but UI doesn’t update	State not updated in handler	Call setState() in the event handler
Memory leak from events	Listener not removed	Always remove listeners in dispose()

@override
void dispose() {
  CometChatMessageEvents.removeMessagesListener("listenerId");
  super.dispose();
}

---

Build and Dependencies

Symptom	Cause	Fix
Dependency conflict	Version mismatch	Run flutter pub upgrade and check version constraints
Build fails with Dart version error	Dart SDK too old	Upgrade Flutter: flutter upgrade
iOS build fails	Pod dependencies outdated	Run cd ios && pod update
Android build fails with Gradle error	Gradle version mismatch	Update Gradle in android/gradle/wrapper/gradle-wrapper.properties
Package not found	Package not in pubspec.yaml	Add cometchat_chat_uikit: ^5.x.x to dependencies

---

Performance

Symptom	Cause	Fix
UI janky/laggy	Too many rebuilds	Use const constructors and optimize state management
Memory usage high	Images not cached	Enable image caching and limit message history
Slow message loading	Large message history	Use pagination with MessagesRequestBuilder().limit
App freezes on large groups	Too many members loaded	Use pagination for group members

---

Common Error Messages

Error	Cause	Fix
ERR_APP_NOT_FOUND	Invalid App ID	Check App ID in Dashboard
ERR_AUTH_TOKEN_NOT_FOUND	Invalid or expired auth token	Generate new auth token
ERR_UID_NOT_FOUND	User doesn’t exist	Create user first via Dashboard or API
ERR_GROUP_NOT_FOUND	Group doesn’t exist	Create group first
ERR_NOT_LOGGED_IN	User not authenticated	Call login() before using SDK
ERR_WEBSOCKET_CONNECTION_FAILED	Network issue	Check internet connection

---

Getting Help

If you’re still experiencing issues:

• Contact CometChat Support