cometchat Ground truth:
cometchat_chat_uikit: ^5.2(legacy/maintenance-only; calls via rawcometchat_calls_sdk ^5.0.2) — pub-cache source +ui-kit/flutter/v5. Official docs: https://www.cometchat.com/docs/ui-kit/flutter/v5/overview · Docs MCP:claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp(or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
CometChat Flutter UIKit v5 — Troubleshooting
Symptom-to-cause lookup and verification checks.
Init / Login Issues
| Symptom | Cause | Fix |
|---|---|---|
| "Authentication null" | CometChatUIKit.init() not called |
Call init before login/components |
| "APP ID null" | appId not set in UIKitSettingsBuilder | Set ..appId = 'YOUR_APP_ID' |
| Login hangs silently | init() hasn't completed yet |
Await init completion via onSuccess before calling login |
| "ERR_INVALID_REGION" | Uppercase region | Use lowercase: 'us', 'eu', 'in' |
| Login succeeds but no messages load | subscriptionType not set |
Set ..subscriptionType = CometChatSubscriptionType.allUsers |
UI / Layout Issues
| Symptom | Cause | Fix |
|---|---|---|
| Theme jank during keyboard animation | CometChatThemeHelper.getColorPalette(context) called in build() |
Cache in didChangeDependencies() |
| Components don't reflect theme changes | Using _themeInitialized flag |
Remove flag — cache unconditionally in didChangeDependencies() |
| Hardcoded colors don't match dark mode | Using Color(0xFF...) instead of theme tokens |
Use colorPalette.primary, colorPalette.textPrimary, etc. |
colorPalette.white doesn't change in dark mode |
white/black/transparent are NOT brightness-aware |
Use colorPalette.neutral50 for brightness-aware white |
GetX Issues
| Symptom | Cause | Fix |
|---|---|---|
| "GetX controller not found" | Using Get.find() before Get.put() |
Let UIKit components manage their own controllers |
| Controller not disposed | Manually created controller without cleanup | Use controllerTag or let widget manage lifecycle |
| Multiple controller instances | Creating controller outside the widget | Let the widget's initState() handle Get.put() |
Get.delete() throws |
Deleting controller that was created with controllerTag |
Only delete if controllerTag was null (widget-managed) |
Listener / Event Issues
| Symptom | Cause | Fix |
|---|---|---|
| Duplicate events firing | Listener not removed in dispose() |
Always remove with same ID used to register |
| Listener ID collision | Hardcoded listener ID string | Use timestamp: 'id_${DateTime.now().millisecondsSinceEpoch}' |
| No typing indicators | subscriptionType not set |
Set CometChatSubscriptionType.allUsers |
| No online/offline status | subscriptionType not set |
Same fix |
ccMessageSent not firing |
Using CometChat.sendMessage() directly |
Use CometChatUIKit.sendTextMessage() instead |
| Events fire after screen disposed | Listener not removed | Remove in dispose() / onClose() |
Call Issues
| Symptom | Cause | Fix |
|---|---|---|
| Incoming call overlay doesn't show | CallNavigationContext.navigatorKey not set |
Set on MaterialApp.navigatorKey |
| Call buttons don't appear | CometChatCallingExtension not registered |
Set ..callingExtension = CometChatCallingExtension() on UIKitSettingsBuilder |
| Call fails silently | Camera/microphone permissions not granted | Request Permission.camera and Permission.microphone |
| Incoming calls not handled | Call listener not registered globally | Register CallListener + CometChatCallEventListener at dashboard level |
Push Notification Issues
| Symptom | Cause | Fix |
|---|---|---|
| No push notifications | Token not registered | Call CometChatNotifications.registerPushToken(PushPlatforms.FCM_FLUTTER_ANDROID, fcmToken: token, ...) after login (PNRegistry.registerPNService is a v5 sample-app extension, not a kit API — must be copied in; see cometchat-flutter-v5-push) |
| Notifications after logout | Token not unregistered | Call CometChatNotifications.unregisterPushToken(onSuccess:, onError:) before logout |
| Duplicate notifications | Foreground notification shown for active conversation | Check conversationId match before showing |
| VoIP call notification doesn't show | Background handler not top-level | Use @pragma('vm:entry-point') on top-level function |
| Tap doesn't navigate | CallNavigationContext.navigatorKey.currentContext is null |
Ensure navigatorKey is set on MaterialApp |
| iOS VoIP token not registered | Missing VoIP background mode | Enable Voice over IP in Xcode Background Modes |
Android Build Issues
| Symptom | Cause | Fix |
|---|---|---|
| Release build crash | Missing ProGuard keep rules | Add -keep class com.cometchat.** { *; } |
| Build fails with minSdk error | minSdk too low | Set minSdk 24 in android/app/build.gradle (matches vendor sample apps; bump to 26 ONLY if calls + min-SDK runtime errors) |
| AndroidX conflict | Missing AndroidX migration | Set BOTH android.useAndroidX=true AND android.enableJetifier=true in gradle.properties |
iOS Build Issues
| Symptom | Cause | Fix |
|---|---|---|
| Camera/mic permission crash | Missing Info.plist entries | Add NSCameraUsageDescription, NSMicrophoneUsageDescription |
| Pod install fails | Cocoapods version mismatch | Run pod repo update then pod install |
Callback Signature Errors
| Symptom | Cause | Fix |
|---|---|---|
Type error on CometChatUsers.onItemTap |
Missing BuildContext parameter |
Signature is Function(BuildContext, User)? |
Type error on CometChatGroups.onItemTap |
Missing BuildContext parameter |
Signature is Function(BuildContext, Group)? |
Type error on CometChatConversations.onItemTap |
Extra BuildContext parameter |
Signature is Function(Conversation)? — no BuildContext |
Type error on CometChatGroupMembers.onItemTap |
Extra BuildContext parameter |
Signature is Function(GroupMember)? — no BuildContext |
v5 vs v6 Drift Detection
If you see any of these in a v5 project, it's a v6 pattern that was accidentally used:
| v6 Pattern (wrong in v5) | v5 Equivalent |
|---|---|
import 'package:flutter_bloc/flutter_bloc.dart' |
GetX — no BLoC in v5 |
extends Bloc<Event, State> |
extends GetxController |
extends Equatable |
Not used in v5 |
ServiceLocator.get<T>() |
Get.find<T>() or let widget manage |
Single cometchat_chat_uikit with calls built-in |
Separate cometchat_calls_uikit package |
Per-component style classes (e.g. CometChatConversationsStyle, CometChatMessageListStyle) + theme via CometChatTheme |
Per-widget feature flags only (no BuilderSettings/BuilderColor/BuilderTypography in v5 — those are v4 leftovers) |
enableCalls: true + CallingConfiguration() on UIKitSettingsBuilder |
..callingExtension = CometChatCallingExtension() |
Verify Checklist
Run through this when something isn't working:
-
CometChatUIKit.init()completes before any other CometChat call -
subscriptionTypeset in UIKitSettingsBuilder -
regionis lowercase - Theme cached in
didChangeDependencies(), notbuild() - All listeners registered with unique IDs
- All listeners removed in
dispose()/onClose() -
CallNavigationContext.navigatorKeyset on MaterialApp -
CometChatCallingExtension()set if using calls - Push tokens registered after login
- Push tokens unregistered before logout
- ProGuard rules present for release builds
- No v6 imports (
flutter_bloc,equatable,BlocProvider/BlocBuilder)