> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-audit-content-webhooks.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 UI Kit.

<Accordion title="AI Agent Component Spec">
  | Field             | Value                                                                                                                                      |
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
  | Page type         | Troubleshooting reference                                                                                                                  |
  | Scope             | All CometChat Flutter UI Kit v5 issues — initialization, rendering, theming, calling, extensions, AI features, localization, sound, events |
  | When to reference | When a component fails to render, data is missing, styling doesn't apply, or a feature doesn't appear                                      |
</Accordion>

## Initialization and Login

| Symptom                                | Cause                                               | Fix                                                                                          |
| -------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `CometChatUIKit.init()` fails silently | Invalid App ID, Region, or Auth Key                 | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/)          |
| Widget doesn't render                  | `init()` not called or not awaited before rendering | Ensure `init()` completes before mounting widgets. See [Methods](/ui-kit/flutter/v5/methods) |
| Widget renders but shows no data       | User not logged in                                  | Call `CometChatUIKit.login("UID")` after init                                                |
| Login fails with "UID not found"       | UID doesn't exist in your CometChat app             | Create the user via Dashboard, SDK, or API first                                             |
| Blank screen after login               | Widget mounted before init/login completes          | Use `FutureBuilder` or state to conditionally render after login resolves                    |
| `getLoggedInUser()` returns null       | User not logged in or session expired               | Call `login()` or `loginWithAuthToken()` first                                               |
| `sendTextMessage()` fails              | User not logged in or invalid receiver              | Ensure login completes before sending messages                                               |
| Auth Key exposed in production         | Using Auth Key instead of Auth Token                | Switch to [Auth Token](/ui-kit/flutter/v5/methods#login-using-auth-token) for production     |

***

## Platform-Specific Issues

### Android

| Symptom                          | Cause                           | Fix                                                                                          |
| -------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- |
| App crashes on launch            | Missing internet permission     | Add `<uses-permission android:name="android.permission.INTERNET"/>` to `AndroidManifest.xml` |
| Network requests fail            | Missing network security config | For debug builds, add `android:usesCleartextTraffic="true"` to `AndroidManifest.xml`         |
| Camera/microphone not working    | Missing permissions             | Add camera and microphone permissions to `AndroidManifest.xml`                               |
| Build fails with minSdk error    | minSdkVersion too low           | Set `minSdkVersion 21` or higher in `build.gradle`                                           |
| ProGuard issues in release build | Missing ProGuard rules          | Add CometChat ProGuard rules to `proguard-rules.pro`                                         |

### iOS

| Symptom                                  | Cause                      | Fix                                                                               |
| ---------------------------------------- | -------------------------- | --------------------------------------------------------------------------------- |
| App crashes on camera/mic access         | Missing Info.plist entries | Add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` to `Info.plist` |
| Build fails with deployment target error | iOS version too low        | Set `platform :ios, '13.0'` or higher in `Podfile`                                |
| Pod install fails                        | CocoaPods cache issue      | Run `pod cache clean --all` then `pod install`                                    |
| Bitcode error                            | Bitcode enabled            | Disable bitcode in Xcode build settings                                           |
| Simulator crashes                        | Architecture mismatch      | Ensure you're using the correct simulator architecture                            |

***

## Theming and Styling

| Symptom                   | Cause                            | Fix                                                                          |
| ------------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| Theme not applied         | Theme not passed to widget       | Wrap your app with `CometChatTheme` or pass theme to individual widgets      |
| Colors not changing       | Using wrong color palette        | Use `CometChatThemeHelper.getColorPalette(context)` to access theme colors   |
| Typography not applied    | Font family not set              | Set font family in `CometChatTypography`                                     |
| Dark mode not working     | Theme mode not set               | Use `ThemeMode.dark` and ensure `CometChatColorPalette` has dark mode colors |
| Custom style not applying | Style property not set correctly | Check the component's style class (e.g., `CometChatConversationsStyle`)      |
| Spacing issues            | Using wrong spacing values       | Use `CometChatSpacing` for consistent spacing                                |

***

## Components

| Symptom                   | Cause                              | Fix                                                                                    |
| ------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
| Callback not firing       | Wrong callback name or signature   | Check the Actions section on the component page for exact callback name and parameters |
| Custom view not appearing | Returning `null` from view builder | Ensure view builder returns a valid Widget                                             |
| Messages not loading      | Invalid user/group object passed   | Ensure you fetch the user/group via SDK before passing to components                   |
| List not refreshing       | State not updated                  | Call `setState()` or use a state management solution                                   |
| Scroll position lost      | Key not set on list items          | Ensure unique keys are set on list items                                               |
| Empty state not showing   | `emptyStateView` not set           | Provide an `emptyStateView` builder                                                    |

***

## Calling

| Symptom                          | Cause                                      | Fix                                                    |
| -------------------------------- | ------------------------------------------ | ------------------------------------------------------ |
| Call buttons not appearing       | Calling extension not installed            | Add `cometchat_calls_uikit` to your `pubspec.yaml`     |
| Incoming call screen not showing | `CometChatIncomingCall` not in widget tree | Add `CometChatIncomingCall` at the app root level      |
| Call fails to connect            | WebRTC permissions not granted             | Ensure camera and microphone permissions are granted   |
| Audio not working in call        | Audio session not configured               | Configure audio session for iOS in `AppDelegate.swift` |
| Video not showing                | Camera permission denied                   | Request camera permission before starting video call   |
| Call drops immediately           | Network connectivity issue                 | Check internet connection and firewall settings        |

***

## Extensions

| Symptom                          | Cause                                | Fix                                                                                    |
| -------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| Extension feature not appearing  | Extension not activated in Dashboard | Enable the specific extension from your [Dashboard](/fundamentals/extensions-overview) |
| Stickers not showing in composer | Sticker extension not enabled        | Activate [Sticker Extension](/fundamentals/stickers) in Dashboard                      |
| Polls option missing             | Polls extension not enabled          | Activate [Polls Extension](/fundamentals/polls) in Dashboard                           |
| Link preview not rendering       | Link Preview extension not enabled   | Activate [Link Preview Extension](/fundamentals/link-preview) in Dashboard             |
| Reactions not working            | Reactions extension not enabled      | Activate [Reactions Extension](/fundamentals/reactions) in Dashboard                   |

***

## AI Features

| Symptom                           | Cause                                          | Fix                                                                                            |
| --------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| AI features not appearing         | Feature not activated in Dashboard             | Enable the specific AI feature from your [Dashboard](/fundamentals/ai-user-copilot/overview)   |
| Conversation Starter not showing  | Feature not enabled or no conversation context | Ensure [Conversation Starter](/fundamentals/ai-user-copilot/conversation-starter) is activated |
| Smart Replies not appearing       | Feature not enabled in Dashboard               | Ensure [Smart Replies](/fundamentals/ai-user-copilot/smart-replies) is activated               |
| AI extension not in UIKitSettings | AI features not configured                     | Add AI extensions to `UIKitSettings.aiFeature` list                                            |

```dart theme={null}
UIKitSettings uiKitSettings = (UIKitSettingsBuilder()
  ..aiFeature = [
    AISmartRepliesExtension(),
    AIConversationStarterExtension(),
    AIConversationSummaryExtension(),
  ]
).build();
```

***

## Localization

| Symptom                           | Cause                            | Fix                                                                  |
| --------------------------------- | -------------------------------- | -------------------------------------------------------------------- |
| UI text not translated            | Language code not matching       | Check supported languages in [Localize](/ui-kit/flutter/v5/localize) |
| Custom translations not appearing | Translations not added correctly | Use `Translations` class to add custom translations                  |
| Date/time format unchanged        | Locale not set                   | Set locale in `MaterialApp` or use `dateTimeFormatterCallback`       |
| RTL layout not working            | Text direction not set           | Set `textDirection: TextDirection.rtl` for RTL languages             |

***

## Sound

| Symptom                                | Cause                          | Fix                                                      |
| -------------------------------------- | ------------------------------ | -------------------------------------------------------- |
| No sound plays                         | Sound disabled or volume muted | Check `CometChatSoundManager` settings and device volume |
| Custom sound not playing               | Invalid file path or format    | Ensure the path is correct and file is WAV/MP3 format    |
| Sound plays multiple times             | Multiple listeners registered  | Ensure you're not registering duplicate sound listeners  |
| Sound continues after app backgrounded | Sound not stopped              | Call `CometChatSoundManager.stop()` when appropriate     |

***

## Events

| Symptom                           | Cause                        | Fix                                                                      |
| --------------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| Event listener not firing         | Subscribed to wrong event    | Check the [Events](/ui-kit/flutter/v5/events) page for exact event names |
| Duplicate event triggers          | Multiple subscriptions       | Remove listener in `dispose()` method                                    |
| Event fires but UI doesn't update | State not updated in handler | Call `setState()` in the event handler                                   |
| Memory leak from events           | Listener not removed         | Always remove listeners in `dispose()`                                   |

```dart theme={null}
@override
void dispose() {
  CometChatMessageEvents.removeMessagesListener("listenerId");
  super.dispose();
}
```

***

## Build and Dependencies

| Symptom                               | Cause                       | Fix                                                                 |
| ------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
| Dependency conflict                   | Version mismatch            | Run `flutter pub upgrade` and check version constraints             |
| Build fails with Dart version error   | Dart SDK too old            | Upgrade Flutter: `flutter upgrade`                                  |
| iOS build fails                       | Pod dependencies outdated   | Run `cd ios && pod update`                                          |
| Android build fails with Gradle error | Gradle version mismatch     | Update Gradle in `android/gradle/wrapper/gradle-wrapper.properties` |
| Package not found                     | Package not in pubspec.yaml | Add `cometchat_chat_uikit: ^5.x.x` to dependencies                  |

***

## Performance

| Symptom                     | Cause                   | Fix                                                    |
| --------------------------- | ----------------------- | ------------------------------------------------------ |
| UI janky/laggy              | Too many rebuilds       | Use `const` constructors and optimize state management |
| Memory usage high           | Images not cached       | Enable image caching and limit message history         |
| Slow message loading        | Large message history   | Use pagination with `MessagesRequestBuilder().limit`   |
| App freezes on large groups | Too many members loaded | Use pagination for group members                       |

***

## Common Error Messages

| Error                             | Cause                         | Fix                                    |
| --------------------------------- | ----------------------------- | -------------------------------------- |
| `ERR_APP_NOT_FOUND`               | Invalid App ID                | Check App ID in Dashboard              |
| `ERR_AUTH_TOKEN_NOT_FOUND`        | Invalid or expired auth token | Generate new auth token                |
| `ERR_UID_NOT_FOUND`               | User doesn't exist            | Create user first via Dashboard or API |
| `ERR_GROUP_NOT_FOUND`             | Group doesn't exist           | Create group first                     |
| `ERR_NOT_LOGGED_IN`               | User not authenticated        | Call `login()` before using SDK        |
| `ERR_WEBSOCKET_CONNECTION_FAILED` | Network issue                 | Check internet connection              |

***

## Getting Help

If you're still experiencing issues:

* Contact [CometChat Support](https://www.cometchat.com/support)