Troubleshooting

Common failure modes and fixes for the CometChat React UI Kit.

AI Agent Component Spec

• 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

Initialization and Login

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