Installation & Setup
| Symptom | Cause | Fix |
|---|---|---|
Gradle sync fails, or org.jitsi:webrtc cannot be resolved | A repository is missing or the version does not match | Declare google(), mavenCentral() and maven { url 'https://dl.cloudsmith.io/public/cometchat/cometchat/maven/' } in your repositories (settings.gradle or the project build.gradle). WebRTC comes from Maven Central. See Setup |
init() fails silently | Invalid App ID or Region | Double-check credentials from the CometChat Dashboard |
| Duplicate class errors | Conflicting WebRTC or transitive dependencies | Exclude conflicting modules in your build.gradle dependencies block |
minSdkVersion error | SDK requires higher minimum API level | Set minSdkVersion to 26 or higher |
| Screen share button is missing | Screen sharing is opt-in from 5.1 | Declare the mediaProjection service and the FOREGROUND_SERVICE_MEDIA_PROJECTION permission. See Screen sharing (opt-in) |
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 call init() and wait for the callback 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 |
| Session joins but no audio/video | Runtime permissions not granted | Request CAMERA and RECORD_AUDIO permissions at runtime before joining |
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 routing issue | Check Audio Modes for speaker/earpiece configuration |
| Camera not working | Permission denied or hardware issue | Verify CAMERA permission is granted and camera is not in use by another app |
| Echo or feedback | Speaker mode with no echo cancellation | Use earpiece mode or headphones |
Background & VoIP
| Symptom | Cause | Fix |
|---|---|---|
| Call drops when app goes to background | No foreground service | Implement a foreground service to keep the call alive. See Background Handling |
| Incoming calls do not ring | Push Notifications SDK calls module missing, push not handed to handlePushNotification, or the device is not ring-ready | Add push-notifications-calls-android, pass every push with sentTimeMs, run ensureRingReady. See Push Ringing |
| Rings, then the process dies before Answer | Call push sent at normal FCM priority (BFGS denied) | Send call pushes at high priority |
| Caller never sees “Ringing…” / answered | Caller joined right after initiateCall | Stay on the prepared session and join on onParticipantJoined. See Ringing |
| Audio call opens the camera | Session type not set at initiateCall | Pass sessionSettings with setSessionType(SessionType.VOICE) in InitiateCallOptions |
| Ring keeps playing after logout | Only the Chat SDK was logged out | Call CometChatCalls.logout too |
| App killed by OS during call | Missing foreground service notification | Show a persistent notification during active calls |
Picture-in-Picture
| Symptom | Cause | Fix |
|---|---|---|
| PiP not working | Missing manifest attribute | Add android:supportsPictureInPicture="true" to your activity in AndroidManifest.xml |
| PiP not available on device | Android version below 8.0 | PiP requires Android 8.0 (API 26) or higher |