Cometchat flutter v5 troubleshooting

Skill cometchat/cometchat-skills/skills/cometchat-flutter-v5-troubleshooting

Add CometChat chat & messaging and voice & video calls to any React, Next.js, React Native, Angular, Android, iOS, or Flutter project through your AI coding agent. Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and 50+ more agents.

Install

npx -y skills add cometchat/cometchat-skills --skill cometchat-flutter-v5-troubleshooting

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its author says it does

Copied from the file, not written here

Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

8.1 KB, as published. Nobody here has run it

Ground truth: cometchat_chat_uikit: ^5.2 (legacy/maintenance-only; calls via raw cometchat_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: