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 |
Screen Sharing
| 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 |
Ringing
| Symptom | Cause | Fix |
|---|---|---|
| Incoming calls do not ring in the browser | The Chat SDK is not logged in, is logged in as another user, or no CometChat.addCallListener is registered | Initialize and log in the Chat SDK as the same user as the Calls SDK, and register the CallListener after login. A closed tab never rings: the web has no VoIP push. See Ringing |
| Every outgoing call is declined “busy” at once | The caller’s own tab treats its outgoing call as incoming (the Chat SDK delivers a 1:1 call message to the caller too) and declines it as busy | In onIncomingCallReceived, skip calls whose getCallInitiator().getUid() is the logged-in user |
| Caller never sees “Ringing…” or “answered” | The callee never prepared the session, the caller’s own prepare failed (call.session.prepareStatus === "failed", so it is not in the room), or the listeners were registered too late | Have the callee call connect(sessionId, settings) as soon as the call rings; register the caller’s listeners right after initiateCall resolves; poll the call’s status, which reports an answer as ongoing |
| Caller keeps ringing after the callee declined | No onOutgoingCallRejected handler on the caller’s CallListener, or the tab missed the message (asleep, reconnecting). A busy decline, or a decline before the callee’s device connected, does not close the caller’s prepared session | Handle onOutgoingCallRejected for your own outgoing call, read the call’s status every 3 s while ringing as a backstop, and run a ring timer that ends the call as unanswered |
| Callee keeps ringing after the caller cancelled | No onIncomingCallCancelled handler, or the tab missed the message (asleep, reconnecting) and the room was not destroyed | Handle onIncomingCallCancelled, and poll the call’s status while ringing as a backstop: stop on anything but initiated for a 1:1 call |
| Audio call opens the camera | Session type not set when the session was prepared | Pass sessionType: "VOICE" in initiateCall’s sessionSettings and to connect; session.join(container) takes no settings |
| One side stays in the call after the other hangs up | The session was not prepared or joined as a peer call | Pass isPeerCall: true for 1:1 calls |
| A call answered in another tab or on another device ends | A tab released its prepared 1:1 session after the call was answered elsewhere: leaving a prepared peer session ends the room | Stop ringing without leave() when the call was answered elsewhere. The prepared session still expires after 5 minutes, or is torn down by the next connect or initiateCall in that tab, with the same effect; there is no local-only leave. See Ringing |
joinSession() returns SESSION_ALREADY_PREPARED | A session is prepared for a ringing call | Join it with session.join(container), or cancel it with session.leave() first |
onSessionTimedOut never fires for an unanswered call | A prepared session that nobody joins reports onConnectionClosed after 5 minutes | Listen for onConnectionClosed, and use your own ring timer |
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 |
onParticipantJoined not called | Listener registered after user already joined | Register listeners before calling joinSession() |