Initialization and Login
| Symptom | Cause | Fix |
|---|---|---|
CometChatUIKit.init() fails silently | Invalid App ID, Region, or Auth Key | Double-check credentials from the CometChat Dashboard |
| Blank screen after login | Component rendered before init() or login() completes | Ensure init() → login() order completes before rendering any UI Kit component. See Methods |
| Component renders but shows no data | User not logged in | Call CometChatUIKit.login("UID") after init resolves |
| Login fails with “UID not found” | UID doesn’t exist in your CometChat app | Create the user via Dashboard, SDK, or REST API first |
CometChatUIKit.loggedInUser returns null | User not logged in or session expired | Call login() or loginWithAuthToken() first |
| Auth Key exposed in production | Using Auth Key instead of Auth Token | Switch to loginWithAuthToken() for production. Generate tokens server-side via the REST API |
Theming and Styling
| Symptom | Cause | Fix |
|---|---|---|
| Theme not applied | ThemeExtension not added to MaterialApp | Add CometChat style extensions to your ThemeData.extensions list |
| Dark mode not working | Brightness not detected | CometChat theme uses MediaQuery.platformBrightnessOf(context). Ensure your MaterialApp supports dark mode |
| Custom colors not applying | Overriding wrong style class | Check Component Styling for the correct style class per component |
| Component-level style ignored | Style object not passed correctly | Ensure you pass the style to the style property, not as a ThemeExtension |
| Styles apply in light mode but not dark | Only light theme configured | Configure both light and dark themes in MaterialApp with separate ThemeData instances |
| Bubble style not applying | Style linked to wrong direction | Define separate styles for CometChatOutgoingMessageBubbleStyle and CometChatIncomingMessageBubbleStyle — changing one does not affect the other |
Components
| Symptom | Cause | Fix |
|---|---|---|
| Component not rendering | init() or login() not complete | Ensure both complete before building any CometChat widget |
| Message list is empty | Invalid User or Group object | Fetch the user or group via the SDK before passing it to the component |
onThreadRepliesClick not firing | Callback not set | Pass the callback to CometChatMessageList(onThreadRepliesClick: ...) |
| Custom template not rendering | Template key doesn’t match message | Ensure type and category on your template match the message’s type and category exactly |
addTemplate not overriding default | Template appended, not replaced | addTemplate appends to the list. The template map uses last-write-wins by category_type key, so your template must have the same key to override |
| Keyboard covers composer | resizeToAvoidBottomInset not set | Set resizeToAvoidBottomInset: true on your Scaffold |
| Swipe-to-reply not working | Disabled or message not eligible | Check enableSwipeToReply is true, message has a valid ID, and is not deleted or an action message |
| Audio playback issues | Multiple audio states | The UI Kit uses AudioStateManager internally. Ensure you’re not conflicting with other audio players |
Calling
| Symptom | Cause | Fix |
|---|---|---|
| Call buttons not appearing | Calls not enabled | Ensure enableCalls = true is set in your UIKitSettingsBuilder |
| Incoming call screen not showing | Call listener not registered | Ensure CometChat.addCallListener() is called in your app initialization |
| Call connects but no audio/video | Missing permissions | Request camera and microphone permissions before initiating calls |
Extensions
| Symptom | Cause | Fix |
|---|---|---|
| Extension feature not appearing | Extension not activated in Dashboard | Enable the specific extension from your Dashboard |
| Stickers not showing | 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 |
BLoC and State Management
| Symptom | Cause | Fix |
|---|---|---|
| BLoC already closed error | External BLoC disposed prematurely | If you provide a custom BLoC via messageListBloc, ensure it outlives the widget |
| State not updating after BLoC event | Event dispatched to wrong BLoC instance | Ensure you’re dispatching events to the same BLoC instance the widget is using |
| Duplicate messages appearing | Multiple BLoC instances for same conversation | Use a single BLoC instance per conversation. Don’t create a new one on every rebuild |
Localization
| Symptom | Cause | Fix |
|---|---|---|
| UI text not translated | Locale not set | Ensure your MaterialApp has the correct locale and supportedLocales configured |
| String overrides not appearing | Wrong key | Verify the key matches exactly. See Localize |
Sound
| Symptom | Cause | Fix |
|---|---|---|
| No sound plays | Sound disabled | Check disableSoundForMessages is not set to true |
| Custom sound not playing | Asset not found | Ensure the sound file is added to your pubspec.yaml assets and the path is correct |
Text Formatters
| Symptom | Cause | Fix |
|---|---|---|
| Mentions render as plain text | Formatter not added | Pass CometChatMentionsFormatter() in the textFormatters list |
textFormatters has no effect | Empty list passed | Add at least one formatter to the list |
| Markdown not rendering | MarkdownTextFormatter not included | Add MarkdownTextFormatter() to your textFormatters list or use RichTextConfiguration on the composer |
Events
| Symptom | Cause | Fix |
|---|---|---|
| Event listener not firing | Subscribed to wrong event class | Check the Events page for exact event class names |
| Duplicate event triggers | Multiple registrations without cleanup | Remove listeners when the widget is disposed |
| Listener ID collision | Non-unique listener tag | Use a unique string for each listener registration |