Troubleshooting - CometChat Docs

AI Integration Quick Reference

Field	Value
Page type	Troubleshooting reference
Packages	`com.cometchat:chatuikit-kotlin-android` · `com.cometchat:chatuikit-compose-android`
Scope	All CometChat Android UI Kit v6 issues — initialization, theming, components, calling, extensions, AI features, localization, sound, events, methods, text formatters
When to reference	When a component fails to render, data is missing, styling doesn’t apply, or a feature doesn’t appear

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", callback)` 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
`getLoggedInUser()` 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
`init()` callback never fires	Network blocked or incorrect region	Verify internet permission in `AndroidManifest.xml` and confirm the region matches your Dashboard (`us`, `eu`, `in`)
`minSdk` build error	Project `minSdk` is below 28	Set `minSdk` to 28 or higher in your app-level `build.gradle` — the UI Kit requires Android 9.0 (API 28)+
Dependency resolution failure	Missing CometChat Maven repository	Add `maven("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/")` to `settings.gradle` repositories block
Wrong import for `CometChatUIKit`	Using old package path	Use `import com.cometchat.uikit.core.CometChatUIKit` for both `chatuikit-kotlin` and `chatuikit-compose` modules

Theming and Styling

Symptom	Cause	Fix
Theme not applied / crash on launch	App theme does not extend `CometChatTheme.DayNight`	Set `parent="CometChatTheme.DayNight"` in your `themes.xml` style and apply it in `AndroidManifest.xml`
Dark mode not working	System dark mode not propagated to CometChat theme	Ensure your app theme parent is `CometChatTheme.DayNight` — it inherits `Theme.MaterialComponents.DayNight.NoActionBar` and responds to system dark mode automatically
Custom colors not applying	Overriding wrong theme attributes	Check the Color Resources page for the correct attribute names
Font not changing	Custom font set on wrong theme attribute	Override `cometchatFontFamily` in your theme to apply a custom font globally
Styles leak into host app	CometChat theme attributes conflict with app theme	Scope CometChat theme overrides to the Activity hosting CometChat components rather than the application-level theme
Styles apply to some screens but not others	Activity uses a different theme	Verify the Activity hosting CometChat components has `android:theme` set to your custom theme in `AndroidManifest.xml`
Changes apply in light mode but not dark mode	Only `values/themes.xml` updated	Update both `values/themes.xml` and `values-night/themes.xml` with your overrides
Drawable changes not visible	Stale build cache	Rebuild the app after adding or replacing drawable files
Bubble style not applying	Custom style linked to wrong hub	Confirm the style is linked inside the correct hub (`CustomIncomingMessageBubbleStyle` or `CustomOutgoingMessageBubbleStyle`). See Message Bubble Styling
Only incoming or outgoing bubble changes	Separate styles required per direction	Define separate styles for incoming and outgoing bubbles — changing one does not affect the other
Component style attribute not recognized	Wrong attribute name	Confirm the exact attribute name in the linked attribute reference file on the component page
Compose theme not applying (`chatuikit-compose`)	Not wrapping in `CometChatTheme` composable	In `chatuikit-compose`, wrap your CometChat composables inside `CometChatTheme { }` to apply theming

Components

Symptom	Cause	Fix
Component not rendering	`init()` or `login()` not complete	Ensure both `init()` and `login()` resolve before inflating any CometChat view. Use a callback or state flag to gate rendering
List is empty despite having data	User not logged in	Verify a user is logged in with `CometChatUIKit.login()` before displaying the component. Components fetch data for the logged-in user only
Callback not firing	Wrong listener method or signature	Check the Actions section on the component page for the exact method name and parameter types
`setOnItemClick` not firing	Selection mode set to `MULTIPLE`	Item clicks may be consumed by selection logic. Set `setSelectionMode(NONE)` if you need standard click behavior
Messages not loading	Invalid `User` or `Group` object passed	Fetch the user or group via the SDK before passing it to the component
View not appearing in XML layout (`chatuikit-kotlin`)	Missing fully qualified class name	Use the full XML element name, e.g. `<com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations />`
Custom view not rendering	`createView` returns `null`	If `createView` returns `null`, the default view is used. Return a valid inflated `View` to replace the default
`ActivityResultLauncher` not initialized	MessageComposer created outside `onCreate`	Create `CometChatMessageComposer` in the `onCreate` state of an Activity. In a Fragment, ensure the Fragment is loaded during the Activity’s `onCreate`
Sticker button disappears after setting auxiliary view	Auxiliary button overridden	Retrieve default auxiliary buttons via `CometChatUIKit.getDataSource().getAuxiliaryOption()` and include them in your custom layout before calling `setAuxiliaryButtonViewListener()`
Typing indicator not showing	Custom subtitle view overrides it	The typing indicator renders in the default subtitle area. When you provide a custom `setSubtitleView`, it replaces the entire subtitle layout including the typing indicator
`disableSoundForMessages(true)` has no effect	Called after component starts loading	Call `disableSoundForMessages(true)` before the component starts loading
Filters not applied	Builder not set on component	Ensure you call the appropriate `set*RequestBuilder(builder)` method on the component instance after creating and configuring the builder
ProGuard/R8 strips CometChat classes	Missing keep rules for CometChat	Add `-keep class com.cometchat.** { *; }` to your `proguard-rules.pro` file
Jetifier errors during build	`android.enableJetifier=true` not set	Add `android.enableJetifier=true` to `gradle.properties`
`CometChatConversationList` not found	Component renamed in v6	Use `CometChatConversations` instead of `CometChatConversationList`
`CometChatThreadedMessagesHeader` not found	Component renamed in v5	Use `CometChatThreadHeader` instead

Calling

Symptom	Cause	Fix
Call buttons not appearing	`com.cometchat:calls-sdk-android` not installed	Add the calls SDK dependency to your `build.gradle` — the UI Kit auto-detects it. See Integration
Incoming call screen not showing	`CometChatIncomingCall` not added to the Activity	Render `CometChatIncomingCall` at the root of your Activity layout so it can listen for incoming calls
Incoming calls not detected	Call events not observed	Ensure you collect from `CometChatEvents.onIncomingCall` SharedFlow in your Application class or relevant scope
Call connects but no audio/video	Missing runtime permissions	Request `CAMERA`, `RECORD_AUDIO`, and `INTERNET` permissions at runtime before initiating calls
Call fails immediately	Calls SDK version mismatch	Ensure `com.cometchat:calls-sdk-android` version is compatible with your UI Kit version. Check the Integration page for version pairing
Sound still plays after disabling	`disableSoundForCalls(true)` called too late	Call `disableSoundForCalls(true)` before the component starts the call. If called after the call is initiated, it may not take effect
Custom call sound not playing	Audio file missing or wrong path	Verify the sound file exists in `res/raw` and pass the correct `@RawRes int` resource ID to `setCustomSoundForCalls`
Call events not received	Not collecting from SharedFlow	Use `CometChatEvents` singleton and collect from the appropriate SharedFlow (e.g., `onCallEnded`, `onIncomingCall`) in a coroutine scope
Call events still firing after screen closed	Coroutine scope not cancelled	Cancel the coroutine scope collecting from `CometChatEvents` SharedFlows in `onDestroy()` or `onDestroyView()`

Extensions

Symptom	Cause	Fix
Extension feature not appearing	Extension not activated in CometChat 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 from action sheet	Polls extension not enabled	Activate Polls Extension in Dashboard
Link preview not rendering in messages	Link Preview extension not enabled	Activate Link Preview Extension in Dashboard

AI Features

Symptom	Cause	Fix
AI features not appearing	Feature not activated in CometChat 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 in Dashboard
Smart Replies not appearing in composer	Feature not enabled in Dashboard	Ensure Smart Replies is activated in Dashboard

Localization

Symptom	Cause	Fix
UI text not translated	Wrong language code	Use a `Language.Code` constant from the supported languages list in Localize
`setLocale` called after UI Kit screens render	Locale applied too late	Call `CometChatLocalize.setLocale(...)` before launching any UI Kit screen
String overrides not appearing	Key name mismatch in `strings.xml`	Verify the key name matches exactly (e.g., `cometchat_chats`). See Localize
Changes not visible after editing `strings.xml`	Stale build cache	Clean and rebuild the project after editing string resources
Date/time labels unchanged	`DateTimeFormatterCallback` not set	Add `setDateTimeFormatterCallback(...)` to the same `UIKitSettings` instance passed to `CometChatUIKit.init()`. See Methods

Sound

Symptom	Cause	Fix
No sound plays	`CometChatSoundManager` created with invalid `Context`	Ensure you pass a valid `Context` when instantiating `CometChatSoundManager`. See Sound Manager
Custom sound not playing	Audio file missing or wrong format	Place audio files in `res/raw` and reference them as `R.raw.<file>`. Ensure the format is supported by Android (WAV/MP3/OGG)
Sound plays only once	Creating a new `CometChatSoundManager` per event	Reuse the same `CometChatSoundManager` instance instead of creating one per event
Silent on device	Device volume or ringer mode	Check device volume and ringer mode settings

Events

Symptom	Cause	Fix
Event not received	Not collecting from the correct `CometChatEvents` SharedFlow	Check the Events page for exact SharedFlow names and collect in a coroutine scope
Duplicate event triggers	Multiple coroutine collectors active	Cancel previous collection scopes when re-subscribing, or use `lifecycleScope` to auto-cancel
Event fires but UI doesn’t update	Callback not running on main thread	Collect SharedFlows using `Dispatchers.Main` or `lifecycleScope.launch { }` to ensure UI updates run on the main thread
Missed events after rotation	Collection scope not re-created after Activity recreation	Collect from `CometChatEvents` SharedFlows in `onCreate()` or `onViewCreated()` using `lifecycleScope`
Not all event types received	Only collecting from some SharedFlows	Each event type has its own SharedFlow on `CometChatEvents`. Collect from every flow you need (e.g., `onGroupCreated`, `onGroupMemberJoined`)

Methods

Symptom	Cause	Fix
UI Kit method fails	Called before `init()` completes	Call `CometChatUIKit.init()` first and wait for the `onSuccess` callback before calling `login()`, `sendTextMessage()`, or any other UI Kit method
Messages sent but UI not updating	Using SDK method instead of UI Kit wrapper	Use `CometChatUIKit.sendTextMessage()` instead of `CometChat.sendTextMessage()`. The UI Kit wrapper automatically updates Message List and Conversations components via internal events
Failures silently ignored	`onError` callback left empty	Every UI Kit method accepts a `CallbackListener` with `onError`. Log the `CometChatException` or display an error message to the user
Session conflicts after switching users	Previous user not logged out	Call `CometChatUIKit.logout()` and wait for `onSuccess` before logging in a different user
Custom message not appearing in Message List	No `MessageTemplate` registered	Custom messages and custom interactive messages require a registered MessageTemplate that defines how to render them
Interactive message missing sender or receiver	`sender` or `receiver` not set	For `FormMessage`, `CardMessage`, `SchedulerMessage`, and `CustomInteractiveMessage`, set both `sender` (via `CometChatUIKit.getLoggedInUser()`) and `receiver` (the target `User` or `Group` object) before sending

Text Formatters

Symptom	Cause	Fix
Mentions render as plain text	Formatter not added to component	Create a `CometChatMentionsFormatter`, add it to a `List<CometChatTextFormatter>`, and pass the list to the component via `setTextFormatters()`
`setTextFormatters()` has no effect	Called with empty list	Add at least one formatter to the list before calling `setTextFormatters()`
Custom mention style not applied in composer	Style not set on formatter	Call `mentionFormatter.setMessageComposerMentionTextStyle(context, R.style.YourStyle)` before passing the formatter to the component
Custom mention style not applied in bubbles	Only one direction styled	Call both `setOutgoingBubbleMentionTextStyle()` and `setIncomingBubbleMentionTextStyle()` — setting only one leaves the other with default style
Shortcut suggestions not appearing	Formatter not registered or extension disabled	Confirm the `ShortCutFormatter` is added to the formatters list via `setTextFormatters()`, and that the `message-shortcuts` extension is enabled in the Dashboard
`setOnMentionClick` callback not firing	Formatter not passed to component	Ensure the formatter is passed to the component via `setTextFormatters()` after calling `setOnMentionClick()`