Troubleshooting - CometChat Docs

Installation & Setup

Symptom	Cause	Fix
`CometChatCalls is not defined`	SDK not installed or not imported	Run `npm install @cometchat/calls-sdk-javascript` and import `CometChatCalls`
`init()` fails silently	Invalid App ID or Region	Double-check credentials from the CometChat Dashboard
`init()` throws network error	Region mismatch or network issue	Ensure the Region matches your app’s region (`us`, `eu`, `in`, `in-private`)
Module not found error	Incorrect import path	Use `import { CometChatCalls } from "@cometchat/calls-sdk-javascript"`

Authentication

Symptom	Cause	Fix
`login()` fails with invalid UID	UID doesn’t exist in CometChat	Create the user via Dashboard or REST API first
Auth token expired	Token has a limited lifetime	Generate a new auth token and call `login()` again
`login()` called before `init()`	SDK not initialized	Always `await CometChatCalls.init()` before calling `login()`

Joining a Session

Symptom	Cause	Fix
`generateToken()` fails	User not logged in or invalid session ID	Ensure `login()` completes before generating a token. Verify the session ID is valid
`joinSession()` shows blank screen	Container element not found or not visible	Ensure the HTML element passed to `CallSettings` exists in the DOM and has dimensions
Session joins but no audio/video	Permissions denied by browser	Prompt the user to allow camera/microphone access. See Permissions Handling
`joinSession()` throws error	Invalid or expired token	Generate a fresh token using `generateToken()` before joining

Audio & Video

Symptom	Cause	Fix
No audio from remote participants	Audio output device issue or muted	Check speaker selection and ensure remote participants are not muted
Camera not working	Another app is using the camera	Close other apps using the camera, or select a different device
Black video tiles	Browser blocked camera access	Check browser permissions. HTTPS is required in production
Echo or feedback	No echo cancellation	Use headphones or enable browser echo cancellation

Symptom	Cause	Fix
Screen share button not working	Browser doesn’t support `getDisplayMedia`	Ensure the browser supports screen sharing. See Browser Compatibility
Screen share fails silently	User cancelled the share dialog	No action needed — this is expected behavior when the user dismisses the dialog
Screen share not visible to others	Network or encoding issue	Check network connectivity and try reducing resolution

HTTPS & Deployment

Symptom	Cause	Fix
Camera/mic permissions blocked	App not served over HTTPS	Use HTTPS in production. Localhost is exempt during development
WebRTC connection fails behind firewall	TURN/STUN servers blocked	Ensure your network allows WebRTC traffic. Contact your network admin
SDK works locally but not in production	Mixed content or CORS issues	Ensure all resources are loaded over HTTPS

Framework-Specific

Symptom	Cause	Fix
SSR error in Next.js	SDK uses browser APIs (`window`, `navigator`)	Use dynamic import with `ssr: false` or wrap in `useEffect`. See Next.js Integration
Component renders but call UI doesn’t appear	Container element not mounted yet	Ensure the DOM element is rendered before calling `joinSession()`
Hot reload breaks call session	SDK state lost on HMR	Rejoin the session after hot reload, or disable HMR during active calls

Events & Callbacks

Symptom	Cause	Fix
Event listener not firing	Wrong event name or listener not registered	Check the Events page for exact event names
Duplicate event triggers	Multiple listeners registered without cleanup	Remove listeners when the component unmounts or before re-registering
`onUserJoined` not called	Listener registered after user already joined	Register listeners before calling `joinSession()`

Migration Guide