Troubleshooting - CometChat Docs

AI Integration Quick Reference

Field	Value
Page type	Troubleshooting reference
Scope	All CometChat React Native UI Kit v5 issues — initialization, rendering, theming, media uploads, calling, extensions, AI features, localization, sound, events, native setup
When to reference	When a component fails to render, data is missing, styling doesn’t apply, a feature doesn’t appear, or native build fails

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

React Native CLI Setup

Symptom	Cause	Fix
Android build fails with Maven error	Missing local Maven repository for `@react-native-async-storage/async-storage`	Add the Maven URL to `android/build.gradle`. See Integration
iOS build fails	Pods not installed	Run `cd ios && pod install && cd ..`
App crashes on launch	`react-native-gesture-handler` not imported at top of entry file	Add `import 'react-native-gesture-handler';` at the very top of `index.js` before any other imports
Permission denied errors on Android	Missing permissions in AndroidManifest.xml	Add required permissions (INTERNET, CAMERA, RECORD_AUDIO, etc.). See Integration
Camera/microphone not working on iOS	Missing Info.plist entries	Add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` to Info.plist

Expo Setup

Symptom	Cause	Fix
App crashes in Expo Go	Expo Go doesn’t support native modules	Use development builds instead of Expo Go
Build fails with native module error	Missing development build	Run `npx expo run:ios` or `npx expo run:android` to create a development build
Permissions not working	Missing app.json configuration	Add iOS `infoPlist` and Android `permissions` to app.json. See Expo Integration

Theming

Symptom	Cause	Fix
Theme not applied	Missing `CometChatThemeProvider` wrapper	Wrap your app with `CometChatThemeProvider`. See Theme
Dark mode not working	`mode` not set in theme prop	Set `theme={{ mode: "dark" }}` on `CometChatThemeProvider`
System theme changes not reflected	App not wrapped in `CometChatThemeProvider`	Wrap app in `CometChatThemeProvider` to enable automatic system theme detection
Custom colors not applying	Colors not in hex format	Ensure all color values are hex strings (e.g., `#F76808`)
Component-level style override not working	Style prop not taking priority	Style props have highest priority — check for typos in prop names
Primary color unchanged	Wrong token name	Use `primary` token under `color` object: `theme={{ light: { color: { primary: "#F76808" } } }}`
Icon styles not applying	Using unsupported imageStyle properties	For default SVG icons, only `tintColor`, `height`, and `width` are supported

Components

Symptom	Cause	Fix
Callback not firing	Wrong prop name or signature	Check the component documentation 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
Gesture handling not working	Missing `GestureHandlerRootView` wrapper	Wrap your app with `GestureHandlerRootView` from `react-native-gesture-handler`
Safe area issues	Missing `SafeAreaProvider` wrapper	Wrap your app with `SafeAreaProvider` from `react-native-safe-area-context`

Media Uploads

Symptom	Cause	Fix
Media or photo upload fails immediately (attachment shows an error icon, rejected before any data transfers)	App’s Media URL Access setting is set to Public URLs	In the CometChat Dashboard, open your app, go to Chat & Messaging → Settings → General Configuration, and set Media URL Access to Presigned URLs. See Pre-Signed URLs
Upload still rejected with Media URL Access set to Presigned URLs	Sender not allowed to send media to this recipient, billing/MIME rule, or file over the size limit	Check the error code on the failed file (e.g. `ERR_PERMISSION_DENIED`, `ERR_PRESIGN_REJECTED`, `ERR_FILE_SIZE_EXCEEDED`). See Upload Files error codes

Calling

Symptom	Cause	Fix
Call buttons not appearing in Message Header	`@cometchat/calls-sdk-react-native` not installed	Run `npm install @cometchat/calls-sdk-react-native` — UI Kit auto-detects it
Incoming call screen not showing	`CometChatIncomingCall` not mounted or call listener not registered	Render `CometChatIncomingCall` at app root and register `CometChat.addCallListener()`. See Call Features
Call accepted but no audio/video	Missing call session setup	After `acceptCall()`, generate a token and render the call component
`onIncomingCallReceived` not firing	Call listener not registered or registered too late	Register `CometChat.addCallListener()` after login completes
Call fails on Android	Missing permissions or wrong SDK version	Ensure `minSdkVersion` is 24+, `compileSdkVersion` is 33+, and permissions are added
Call fails on iOS	Missing permissions or wrong deployment target	Set `IPHONEOS_DEPLOYMENT_TARGET` to 12.0+ and add camera/microphone permissions to Info.plist
WebRTC errors	Missing peer dependencies	Install `react-native-webrtc`, `@react-native-community/netinfo`, `react-native-background-timer`

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
Collaborative whiteboard/document not appearing	Extension not enabled	Activate Collaborative Whiteboard or Collaborative Document 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`)
Auto language detection not working	Missing `react-native-localize` package	Install `react-native-localize`: `npm install react-native-localize`
Custom translations not appearing	`CometChatI18nProvider` not wrapping app	Wrap app with `CometChatI18nProvider` inside `CometChatThemeProvider`
`useCometChatTranslation` returns undefined	Hook used outside provider	Ensure component is wrapped by `CometChatI18nProvider`
Fallback language not working	`fallbackLanguage` prop not set	Set `fallbackLanguage` prop on `CometChatI18nProvider`

Sound

Symptom	Cause	Fix
No sound plays	Audio file not found or unsupported format	Ensure the path is correct and the file is a valid audio format (WAV/MP3)
Custom sound not playing	Invalid file path	Verify the asset path is correct; use `isRequire: true` if using `require()` for local assets
Sound keeps playing	`pause()` not called	Call `CometChatSoundManager.pause()` to stop playback
Sound plays multiple times	Multiple sound triggers	Ensure you’re not calling `play()` multiple times for the same event

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	Remove listeners 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
Call events not received	`CometChatUIEventHandler` listener not registered	Register both `CometChat.addCallListener()` and `CometChatUIEventHandler.addCallListener()`

Native Dependencies

Symptom	Cause	Fix
`react-native-video` not working	Native module not linked	For React Native CLI, run `cd ios && pod install`. For Expo, use development builds
`react-native-svg` icons not rendering	Package not installed or linked	Install `react-native-svg` and run `pod install` for iOS
`@react-native-clipboard/clipboard` errors	Package not installed	Install `@react-native-clipboard/clipboard`
`@react-native-community/datetimepicker` errors	Package not installed	Install `@react-native-community/datetimepicker`
`dayjs` date formatting issues	Package not installed	Install `dayjs`