AI Agent Component Spec
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 Kit5.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
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