Troubleshooting - CometChat Docs

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

Custom Text Formatter Guide

⌘I