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 |
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() |