> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-react-v7-feature-guides.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                                             |
| Video thumbnails show a grey box (image thumbnails render fine) | The default v4 Chat SDK does not pass the generated thumbnail URL correctly, so it fails to load | Override `cometchat_sdk` to `5.0.4`, see [Video thumbnails not rendering](#video-thumbnails-not-rendering) below |

***

### Video thumbnails not rendering

With Flutter UI Kit `5.2.x`, the message list resolves the Thumbnail Generation extension's `cometchat_sdk` (the v4 Chat SDK) by default. On that version, the generated thumbnail URL is not passed correctly, so video thumbnails fail to load and fall back to a grey box with a play icon.

Image thumbnails are unaffected because they fall back to the full image URL, which is why only videos appear broken.

This is resolved in the v5 Chat SDK. Since the UI Kit still resolves the v4 SDK by default, pin the SDK version using `dependency_overrides` in your app's `pubspec.yaml`:

```yaml theme={null}
dependency_overrides:
  cometchat_sdk: 5.0.4
```

Then reinstall dependencies and do a clean rebuild:

```bash theme={null}
flutter clean
flutter pub get
```

<Note>
  Use version `5.0.4` specifically. Avoid overriding to the latest v5 SDK, as newer releases include changes that can cause compile-time issues with UI Kit `5.2.x`.
</Note>

***

## 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)