About

Imported from cometchat/cometchat-skills (skills/cometchat-flutter-v5-troubleshooting/SKILL.md). Install upstream with npx skills add cometchat/cometchat-skills --skill cometchat-flutter-v5-troubleshooting. Copyright stays with the author (MIT).

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

Name: cometchat-flutter-v5-troubleshooting
Author: cometchat

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:

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/cometchat-cometchat-skills-cometchat-flutter-v5-troubleshooting/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

cometchat-cometchat-skills-cometchat-flutter-v5-troubleshooting.ocm.jsonjson

{
  "ocm": "1",
  "id": "cometchat-cometchat-skills-cometchat-flutter-v5-troubleshooting",
  "kind": "skill",
  "name": "cometchat-flutter-v5-troubleshooting",
  "description": "Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection.",
  "publisher": "cometchat",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "medical"
    ],
    "tags": [
      "skill-md",
      "cometchat",
      "flutter",
      "v5",
      "troubleshooting",
      "debug",
      "errors",
      "fix",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/cometchat/cometchat-skills",
      "path": "skills/cometchat-flutter-v5-troubleshooting/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/cometchat/cometchat-skills/blob/HEAD/skills/cometchat-flutter-v5-troubleshooting/SKILL.md",
      "key": "cometchat/cometchat-skills/skills/cometchat-flutter-v5-troubleshooting/SKILL.md"
    },
    "compatibility": "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3",
    "license": "MIT"
  },
  "instructions": "> **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.\n\n# CometChat Flutter UIKit v5 — Troubleshooting\n\nSymptom-to-cause lookup and verification checks.\n\n## Init / Login Issues\n\n| Symptom | Cause | Fi",
  "cost": {
    "context_tokens": 1963
  }
}

Fetch it by URL: GET /api/v1/registry/cometchat-cometchat-skills-cometchat-flutter-v5-troubleshooting/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.