> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common failure modes and fixes for the CometChat Flutter SDK.

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

<Accordion title="AI Integration Quick Reference">
  | 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 |
  | `pod install` fails | Run `pod install --repo-update` in the `ios/` directory |
  | Android build fails | Verify `minSdkVersion` meets SDK requirement |
</Accordion>

***

## 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()` resolves before calling other methods. Use `await` |
| 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 load 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` |

***

## 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 `MessageListener` with `onTextMessageReceived` |
| Duplicate messages | Multiple listeners | Use unique listener IDs. Remove old listeners in `dispose()` |
| Wrong conversation | Wrong receiver type | Use `CometChatReceiverType.user` for 1:1, `CometChatReceiverType.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 | Set `metadata` before calling 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 admin to add you |
| Owner can't leave | Ownership not transferred | Call `transferGroupOwnership()` first |
| Password join fails | Wrong password | Pass correct password as the `password` parameter |
| `fetchNext()` returns same results | New request object | Reuse the same `GroupsRequest` instance |
| Scope filter returns nothing | Invalid strings | Use `CometChatMemberScope.admin`, `.moderator`, `.participant` |
| Cannot demote admin | Not owner | Only 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 installed | Add `cometchat_calls_sdk` to `pubspec.yaml` and run `flutter pub get` |
| No audio/video | Permissions denied | Check device permissions for camera/microphone. Add required entries to `Info.plist` (iOS) and `AndroidManifest.xml` (Android) |
| Call not connecting | Session ID mismatch | Verify both participants use same session ID |
| One-way audio | Firewall blocking WebRTC | Check network config. Corporate networks may block WebRTC |
| Incoming call not showing | Listener not registered | Register `CallListener` at app root level |
| Call ended event not received | Wrong callback | Use `onCallEndedMessageReceived` in `CallListener` for call-end messages |
| Black screen after joining | Widget not visible | Ensure the call widget has proper dimensions and is in the widget tree |

***

## 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 |
| Connection drops frequently | Network instability | Use `ConnectionListener` 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)` was set |
| `connect()` doesn't work | Not logged in | Ensure user is logged in first |

***

## Listeners

| Symptom | Cause | Fix |
| - | - | - |
| Events not firing | Registered before init | Register after `init()` and `login()` complete |
| Duplicate events | Multiple listeners | Remove old listeners before adding new ones |
| Missing events after navigation | Listeners removed | Re-register when new widget mounts (in `initState()`) |
| Receipt events not triggering | Receipts not sent | Call `markAsDelivered()`/`markAsRead()` explicitly |

***

## Typing, Receipts & Reactions

| Symptom | Cause | Fix |
| - | - | - |
| Typing indicator stuck | `endTyping()` not called | Call on send, focus lost, or after 3–5s timeout |
| 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 | Update UI state when `onMessageReactionAdded` fires |
| Duplicate reactions | No check before adding | Check `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 |

***

## Platform-Specific — iOS

| Symptom | Cause | Fix |
| - | - | - |
| `pod install` fails | Outdated CocoaPods cache | Run `pod install --repo-update` in the `ios/` directory |
| Build fails on simulator | Architecture mismatch | Add `arm64` to excluded architectures for simulator builds in Xcode |
| "Module not found" error | Pods not installed | Run `cd ios && pod install` after adding the dependency |
| Camera/microphone not working | Missing `Info.plist` entries | Add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` to `ios/Runner/Info.plist` |
| Push notifications not received | APNs not configured | Configure APNs certificates in Dashboard and register token with `CometChatNotifications.registerPushToken()` |

## Platform-Specific — Android

| Symptom | Cause | Fix |
| - | - | - |
| Build fails with "minSdk" error | API level too low | Set `minSdkVersion` in `android/app/build.gradle` to the required level |
| Multidex error | Too many methods | Enable multidex in `android/app/build.gradle`: `multiDexEnabled true` |
| Camera/microphone not working | Missing permissions | Add `CAMERA`, `RECORD_AUDIO`, and `MODIFY_AUDIO_SETTINGS` to `AndroidManifest.xml` |
| FCM notifications not received | FCM not configured | Configure FCM in Dashboard and register token with `CometChatNotifications.registerPushToken()` |
| ProGuard stripping SDK classes | Missing ProGuard rules | Add CometChat ProGuard rules to `proguard-rules.pro` |

***

## Error Codes

For the complete SDK error code reference, see [Error Codes](/sdk/flutter/v4/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/flutter/v4/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

<CardGroup cols={2}>
  <Card title="Setup SDK" icon="gear" href="/sdk/flutter/setup">
    Installation and initialization guide
  </Card>

  <Card title="Best Practices" icon="check" href="/sdk/flutter/v4/best-practices">
    Recommended patterns and practices
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/sdk/flutter/v4/error-codes">
    Complete SDK error code reference
  </Card>

  <Card title="Support" icon="headset" href="https://help.cometchat.com/hc/en-us/requests/new">
    Open a support ticket
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.