> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Troubleshoot common setup, authentication, messaging, and connection issues in the CometChat Android SDK.
Find solutions to common issues when building with the CometChat Android SDK.
| Issue | Fix |
| -------------------------------- | -------------------------------------------------------------------- |
| `init()` fails | Verify App ID and Region from [Dashboard](https://app.cometchat.com) |
| 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](https://app.cometchat.com) → 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](https://app.cometchat.com) or [REST API](https://api-explorer.cometchat.com/reference/creates-user) |
| 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](https://api-explorer.cometchat.com/reference/create-authtoken) |
| 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 `` 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](https://app.cometchat.com) → 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](/sdk/android/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](/sdk/android/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
Installation and initialization guide
Recommended patterns and practices
Complete SDK error code reference
AI Agents, Moderation, and Copilot
Open a support ticket