Troubleshooting - CometChat Docs

Find solutions to common issues when building with the CometChat Android SDK.

AI Integration Quick Reference

Issue	Fix
`init()` fails	Verify App ID and Region from Dashboard
Login fails with “UID not found”	Create user via Dashboard or REST API first
SDK methods fail	Ensure `init()` completes before calling other methods
No real-time events	Check WebSocket connection, verify listeners registered
Build fails	Check Gradle dependency version and repository URL

Initialization & Authentication

Symptom	Cause	Fix
`init()` fails with “App ID not found”	Invalid App ID or Region	Verify credentials in Dashboard → API & Auth Keys
`init()` fails silently	Missing credentials	Double-check App ID and Region are non-null strings
”CometChat not initialized”	`init()` not awaited	Ensure `init()` callback’s `onSuccess` fires before calling other methods
Login fails with “UID not found”	User doesn’t exist	Create user via Dashboard or REST API
Login fails with “Auth Key is not valid”	Wrong Auth Key	Verify Auth Key in Dashboard. Don’t confuse with REST API Key
`getLoggedInUser()` returns null	Session cleared or `init()` not called	Call `init()` on every app start before checking session
Auth Token expired	Token lifetime exceeded	Generate new token via REST API
User appears offline after login	Presence not configured	Use `subscribePresenceForAllUsers()` in `AppSettingsBuilder`

Gradle & Build Issues

Symptom	Cause	Fix
`Could not resolve com.cometchat:chat-sdk-android`	Missing repository	Add `https://dl.cloudsmith.io/public/cometchat/cometchat/maven/` to your project-level `build.gradle` repositories block
Duplicate class errors at compile time	Multiple versions of a dependency	Run `./gradlew dependencies` to find conflicts. Use `exclude group:` or force a single version
`Manifest merger failed`	Conflicting `minSdkVersion`	Set `minSdkVersion` to at least 21 (24 if using the Calls SDK) in your app-level `build.gradle`
`Java 8 features not supported`	Missing compile options	Add `compileOptions { sourceCompatibility JavaVersion.VERSION_1_8; targetCompatibility JavaVersion.VERSION_1_8 }` to your `android` block
Build succeeds but crashes on launch	AndroidX not enabled	Add `android.useAndroidX=true` and `android.enableJetifier=true` to `gradle.properties`
Calls SDK not found	Not added to Gradle	Add `implementation 'com.cometchat:calls-sdk-android:4.x.x'` to your app-level `build.gradle`

Permissions

Symptom	Cause	Fix
App crashes when sending media	Missing storage permission	Request `READ_EXTERNAL_STORAGE` / `READ_MEDIA_IMAGES` at runtime before file access
No audio in calls	`RECORD_AUDIO` not granted	Request `RECORD_AUDIO` permission before initiating or joining a call
No video in calls	`CAMERA` not granted	Request `CAMERA` permission before initiating or joining a video call
Permission dialog never appears	Permission not declared in manifest	Add the required `<uses-permission>` tags to `AndroidManifest.xml`
Permission permanently denied	User selected “Don’t ask again”	Use `shouldShowRequestPermissionRationale()` to detect this and direct the user to app settings

ProGuard & Release Builds

Symptom	Cause	Fix
App works in debug but crashes in release	ProGuard stripping SDK classes	Add CometChat ProGuard rules (see below) to your `proguard-rules.pro`
`ClassNotFoundException` in release build	Obfuscation removing required class	Ensure `-keep class com.cometchat.**` rules are applied
JSON parsing errors in release	Model class fields renamed by ProGuard	Add `-keepclassmembers` rules for SDK model classes
Calls SDK crashes in release	Calls SDK classes obfuscated	Add `-keep class com.cometchat.calls.**` to your ProGuard rules

Add these rules to your proguard-rules.pro:

-keep class com.cometchat.** { *; }
-keep class com.cometchat.calls.** { *; }
-dontwarn com.cometchat.**

Messaging

Symptom	Cause	Fix
`sendMessage()` fails	Not logged in or invalid receiver	Ensure `login()` completes. Verify receiver UID/GUID exists
Messages sent but not received	Listener not registered	Register `addMessageListener()` with `onTextMessageReceived`
Duplicate messages	Multiple listeners with same ID	Use unique listener IDs. Remove old listeners before re-registering
Wrong conversation	Wrong receiver type	Use `CometChatConstants.RECEIVER_TYPE_USER` for 1:1, `RECEIVER_TYPE_GROUP` for groups
Media upload fails	File too large or unsupported	Check limits. Supported: PNG, JPG, GIF, MP4, MP3, WAV
Metadata not appearing	Set after send	Call `setMetadata()` before the send method
Pagination not working	New request object	Reuse the same `MessagesRequest` for `fetchPrevious()`/`fetchNext()`
Thread replies in main chat	Missing filter	Add `.hideReplies(true)` to `MessagesRequestBuilder`
Deleted messages showing	Missing filter	Add `.hideDeletedMessages(true)`

Groups

Symptom	Cause	Fix
Cannot join group	Invalid GUID	Verify GUID. Create group first if needed
Cannot send to group	Not a member	Join group first with `joinGroup()`
Cannot kick/ban members	Insufficient scope	Only admins and moderators can kick/ban
Can’t join private group	Requires invite	Private groups require an admin to add you
Owner can’t leave	Ownership not transferred	Call `transferGroupOwnership()` first
Password join fails	Wrong password	Pass correct password as the third parameter
`fetchNext()` returns same results	New request object	Reuse the same `GroupsRequest` instance
Scope filter returns nothing	Invalid strings	Use `"admin"`, `"moderator"`, `"participant"`
Cannot demote admin	Not owner	Only the group owner can demote admins
Kicked user can still see group	Kick vs ban	Use `banGroupMember()` to prevent rejoining

Calling

Symptom	Cause	Fix
Calls SDK not found	Not added to Gradle	Add `implementation 'com.cometchat:calls-sdk-android:4.x.x'`
No audio/video	Permissions denied	Request `CAMERA` and `RECORD_AUDIO` permissions at runtime before the call
Call not connecting	Session ID mismatch	Verify both participants use the same session ID
One-way audio	Firewall blocking WebRTC	Check network config. Corporate networks may block WebRTC ports
Incoming call not showing	Listener not registered	Register `addCallListener()` at the Application or root Activity level
Call ended event not received	Wrong callback	Use `onCallEndedMessageReceived` in `CallListener` for call-end messages, `onCallEnded` in `OngoingCallListener` for session events
Black screen after joining	View not visible or sized	Ensure the call container `View` has non-zero dimensions and is visible
Calls crash in release build	ProGuard stripping classes	Add `-keep class com.cometchat.calls.** { *; }` to `proguard-rules.pro`

WebSocket & Connection

Symptom	Cause	Fix
Real-time events not received	WebSocket disconnected	Check `getConnectionStatus()`. Reconnect if needed
WebSocket fails	Firewall blocking	Check network config. Corporate firewalls may block WebSocket connections
Connection drops frequently	Network instability	Use `addConnectionListener()` to monitor and reconnect
Stuck in “connecting”	Network or config issue	Verify network, `appId`, and `region`
`featureThrottled` status	Feature rate-limited	Reduce frequency of the throttled feature. Listen for `onFeatureThrottled` in `ConnectionListener`
No events after login	Auto-connect disabled	Call `CometChat.connect()` manually if `autoEstablishSocketConnection(false)`
`connect()` doesn’t work	Not logged in	Ensure user is logged in first

Listeners & Lifecycle

Symptom	Cause	Fix
Events not firing	Registered before init	Register after `init()` and `login()` complete
Duplicate events	Multiple listeners with same ID	Remove old listeners before adding new ones
Missing events after navigation	Listeners removed on `onPause()`	Re-register in `onResume()` when the screen becomes active
Events fire after screen is closed	Listeners not removed	Remove listeners in `onPause()` or `onDestroy()`
Receipt events not triggering	Receipts not sent	Call `markAsDelivered()`/`markAsRead()` explicitly
Memory leaks	Listeners holding Activity reference	Always remove listeners in `onDestroy()`

Typing, Receipts & Reactions

Symptom	Cause	Fix
Typing indicator stuck	`endTyping()` not called	Call on send, focus loss, or after 3–5s timeout using a `Handler`
Double-tick not showing	`markAsDelivered()` not called	Call on message fetch and real-time receive
Group receipts missing	Feature not enabled	Enable “Enhanced Messaging Status” in Dashboard
`onMessagesDeliveredToAll`/`onMessagesReadByAll` not firing	Not registered	Register these callbacks in `MessageListener` for group-level receipt events
Reaction not appearing	UI not synced	Call `updateMessageWithReactionInfo()` on events
Duplicate reactions	No check before adding	Use `getReactedByMe()` first

AI Features

Symptom	Cause	Fix
AI features not appearing	Not enabled	Enable in Dashboard → AI Features
AI Agents not responding	Not configured	Configure Agent in Dashboard. Agents only respond to text
`onAIAssistantEventReceived` not firing	Listener not registered	Register `AIAssistantListener` after login
Moderation always PENDING	Rules not configured	Configure rules in Dashboard → Moderation → Rules
Agentic messages not arriving	Wrong listener	Use `MessageListener` with `onAIAssistantMessageReceived`

Upgrading from V3

Symptom	Cause	Fix
Build fails after upgrade	Old artifact still in Gradle	Replace `com.cometchat:chat-sdk-android:3.x.x` with `com.cometchat:chat-sdk-android:4.x.x`
Calls SDK not working	Wrong artifact version	Use `com.cometchat:calls-sdk-android:4.x.x`
Both versions installed	Gradle conflict	Remove the v3 dependency and sync project

Error Codes

For the complete SDK error code reference, see Error Codes. Common errors you’ll encounter:

Code	Description	Resolution
`ERR_UID_NOT_FOUND`	User doesn’t exist	Create user via Dashboard or REST API
`AUTH_ERR_AUTH_TOKEN_NOT_FOUND`	Invalid or expired auth token	Generate new token via REST API
`MISSING_PARAMETERS`	Required parameter not provided	Check method signature and pass all required params
`NOT_INITIALIZED`	`init()` not called	Call `CometChat.init()` before any other method
`USER_NOT_LOGGED_IN`	No active session	Call `login()` first
`ERR_GUID_NOT_FOUND`	Group doesn’t exist	Create group or verify GUID
`ERR_NOT_A_MEMBER`	Not a group member	Join group first
`TOO_MANY_REQUEST`	Rate limit exceeded	See Rate Limits
`FAILED_TO_FETCH`	Network issue	Check internet connection and API endpoint
`NO_WEBSOCKET_CONNECTION`	WebSocket disconnected	Check connection status, wait for reconnect

Next Steps

Setup SDK

Installation and initialization guide

Best Practices

Recommended patterns and practices

Error Codes

Complete SDK error code reference

AI Integration

AI Agents, Moderation, and Copilot

Support

Open a support ticket

​Initialization & Authentication

​Gradle & Build Issues

​Permissions

​ProGuard & Release Builds

​Messaging

​Groups

​Calling

​WebSocket & Connection

​Listeners & Lifecycle

​Typing, Receipts & Reactions

​AI Features

​Upgrading from V3

​Error Codes

​Next Steps

Setup SDK

Best Practices

Error Codes

AI Integration

Support

Initialization & Authentication

Gradle & Build Issues

Permissions

ProGuard & Release Builds

Messaging

Groups

Calling

WebSocket & Connection

Listeners & Lifecycle

Typing, Receipts & Reactions

AI Features

Upgrading from V3

Error Codes

Next Steps