Troubleshooting - CometChat Docs

AI Integration Quick Reference

Field	Value
Page type	Troubleshooting reference
Scope	All CometChat React UI Kit v6 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

Symptom	Cause	Fix
`CometChatUIKit.init()` fails silently	Invalid App ID, Region, or Auth Key	Double-check credentials from the CometChat Dashboard
Component doesn’t render	`init()` not called or not awaited before rendering	Ensure `init()` completes before mounting components. See Methods
Component 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	Component mounted before init/login completes	Use 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

SSR / Framework-Specific

Symptom	Cause	Fix
SSR hydration error	CometChat components use browser APIs (`window`, `WebSocket`, `document`) on server	Wrap in `useEffect` or use dynamic import with `ssr: false`. See Next.js Integration
CometChat components fail in Astro	Astro SSR tries to render on server	Use `client:only="react"` directive on CometChat islands

Theming and CSS

Symptom	Cause	Fix
CSS/theme not applied	Missing CSS import	Add `@import url("@cometchat/chat-uikit-react/css-variables.css");` in your CSS entry file
CSS has no effect	Base stylesheet not imported	Add `@import url("@cometchat/chat-uikit-react/css-variables.css");` at top of `App.css`
Overrides not applying	Missing `.cometchat` scope in selector	Scope overrides under `.cometchat`
Selectors don’t match	Using CSS Modules (hashed class names)	Move rules to a global stylesheet, not `*.module.css`
Component-level override not working	Missing `.cometchat` parent in selector	Use `.cometchat .cometchat-conversations` not just `.cometchat-conversations`
Dark mode unchanged	`data-theme` missing or mismatch	Set `data-theme="dark"` on the wrapper and target `.cometchat-root[data-theme="dark"] .cometchat`
Font not changing	`--cometchat-font-family` set on wrong element	Set on `.cometchat`
Styles leak into host app	Missing `.cometchat` scope prefix	Always scope overrides under `.cometchat`
Token change has no visible effect	Token doesn’t control the expected property	Check the Color Resources table

Components

Symptom	Cause	Fix
Callback not firing	Wrong prop name or signature	Check the Actions section on the component page for exact prop name and parameter types
Custom view not appearing	Returning `null` or `undefined` from view prop	Ensure view function returns valid JSX
Messages not loading	Invalid user/group object passed	Ensure you fetch the user/group via SDK before passing to components

Calling

Symptom	Cause	Fix
Call buttons not appearing in Message Header	`@cometchat/calls-sdk-javascript` not installed	Run `npm install @cometchat/calls-sdk-javascript` — UI Kit auto-detects it
Incoming call screen not showing	`CometChatIncomingCall` not mounted in the component tree	Render the component at the app root level so it can listen for incoming calls

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	Language code not matching supported codes	Check the supported languages table in Localize for exact codes (e.g., `en-US` not `en`)
Custom translations not appearing	`addTranslation` called before `init`	Call `CometChatLocalize.init()` first, then `addTranslation()`
Date/time format unchanged	`disableDateTimeLocalization` set to `true`	Set `disableDateTimeLocalization: false` in init config
Component-level CalendarObject ignored	Prop name mismatch	Check the component docs for the exact prop name (e.g., `lastActiveAtDateTimeFormat`)
Missing translation key shows raw key	No `missingKeyHandler` configured	Add a `missingKeyHandler` function in init config

Sound

Symptom	Cause	Fix
No sound plays	Browser autoplay policy blocks audio before user interaction	`hasInteracted()` must return `true` — the user must interact with the page first
Custom sound not playing	Invalid file path or unsupported format	Ensure the path is correct and the file is a valid audio format (WAV/MP3)
Sound keeps playing	`pause()` not called	Call `CometChatSoundManager.pause()` to stop playback
`Sound` import error	`Sound` is not a separate export	Access via `CometChatSoundManager.Sound`, not `import { Sound }`

Events

Symptom	Cause	Fix
Event listener not firing	Subscribed to wrong event name	Check the Events page for exact event names
Duplicate event triggers	Multiple subscriptions without cleanup	Unsubscribe in `useEffect` cleanup or component unmount
Event fires but UI doesn’t update	State not updated in event handler	Ensure you call `setState` or equivalent in the handler

⌘I