{"id":"6ecabc7b-65c0-4a01-a06b-6edd0ae85797","shortId":"4hfjnT","kind":"skill","title":"cometchat-flutter-v5-troubleshooting","tagline":"Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection.","description":"# CometChat Flutter UIKit v5 — Troubleshooting\n\nSymptom-to-cause lookup and verification checks.\n\n## Init / Login Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| \"Authentication null\" | `CometChatUIKit.init()` not called | Call init before login/components |\n| \"APP ID null\" | appId not set in UIKitSettingsBuilder | Set `..appId = 'YOUR_APP_ID'` |\n| Login hangs silently | `init()` hasn't completed yet | Await init completion via `onSuccess` before calling login |\n| \"ERR_INVALID_REGION\" | Uppercase region | Use lowercase: `'us'`, `'eu'`, `'in'` |\n| Login succeeds but no messages load | `subscriptionType` not set | Set `..subscriptionType = CometChatSubscriptionType.allUsers` |\n\n## UI / Layout Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Theme jank during keyboard animation | `CometChatThemeHelper.getColorPalette(context)` called in `build()` | Cache in `didChangeDependencies()` |\n| Components don't reflect theme changes | Using `_themeInitialized` flag | Remove flag — cache unconditionally in `didChangeDependencies()` |\n| Hardcoded colors don't match dark mode | Using `Color(0xFF...)` instead of theme tokens | Use `colorPalette.primary`, `colorPalette.textPrimary`, etc. |\n| `colorPalette.white` doesn't change in dark mode | `white`/`black`/`transparent` are NOT brightness-aware | Use `colorPalette.neutral50` for brightness-aware white |\n\n## GetX Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| \"GetX controller not found\" | Using `Get.find()` before `Get.put()` | Let UIKit components manage their own controllers |\n| Controller not disposed | Manually created controller without cleanup | Use `controllerTag` or let widget manage lifecycle |\n| Multiple controller instances | Creating controller outside the widget | Let the widget's `initState()` handle `Get.put()` |\n| `Get.delete()` throws | Deleting controller that was created with `controllerTag` | Only delete if `controllerTag` was null (widget-managed) |\n\n## Listener / Event Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Duplicate events firing | Listener not removed in `dispose()` | Always remove with same ID used to register |\n| Listener ID collision | Hardcoded listener ID string | Use timestamp: `'id_${DateTime.now().millisecondsSinceEpoch}'` |\n| No typing indicators | `subscriptionType` not set | Set `CometChatSubscriptionType.allUsers` |\n| No online/offline status | `subscriptionType` not set | Same fix |\n| `ccMessageSent` not firing | Using `CometChat.sendMessage()` directly | Use `CometChatUIKit.sendTextMessage()` instead |\n| Events fire after screen disposed | Listener not removed | Remove in `dispose()` / `onClose()` |\n\n## Call Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Incoming call overlay doesn't show | `CallNavigationContext.navigatorKey` not set | Set on `MaterialApp.navigatorKey` |\n| Call buttons don't appear | `CometChatCallingExtension` not registered | Set `..callingExtension = CometChatCallingExtension()` on UIKitSettingsBuilder |\n| Call fails silently | Camera/microphone permissions not granted | Request `Permission.camera` and `Permission.microphone` |\n| Incoming calls not handled | Call listener not registered globally | Register `CallListener` + `CometChatCallEventListener` at dashboard level |\n\n## Push Notification Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| No push notifications | Token not registered | Call `PNRegistry.registerPNService(token, isFcm, isVoip)` |\n| Notifications after logout | Token not unregistered | Call `PNRegistry.unregisterPNService()` before logout |\n| Duplicate notifications | Foreground notification shown for active conversation | Check `conversationId` match before showing |\n| VoIP call notification doesn't show | Background handler not top-level | Use `@pragma('vm:entry-point')` on top-level function |\n| Tap doesn't navigate | `CallNavigationContext.navigatorKey.currentContext` is null | Ensure `navigatorKey` is set on MaterialApp |\n| iOS VoIP token not registered | Missing VoIP background mode | Enable Voice over IP in Xcode Background Modes |\n\n## Android Build Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Release build crash | Missing ProGuard keep rules | Add `-keep class com.cometchat.** { *; }` |\n| Build fails with minSdk error | minSdk too low | Set `minSdk 26` in `android/app/build.gradle` |\n| AndroidX conflict | Missing AndroidX migration | Set `android.useAndroidX=true` in `gradle.properties` |\n\n## iOS Build Issues\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Camera/mic permission crash | Missing Info.plist entries | Add `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` |\n| Pod install fails | Cocoapods version mismatch | Run `pod repo update` then `pod install` |\n\n## Callback Signature Errors\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Type error on `CometChatUsers.onItemTap` | Missing `BuildContext` parameter | Signature is `Function(BuildContext, User)?` |\n| Type error on `CometChatGroups.onItemTap` | Missing `BuildContext` parameter | Signature is `Function(BuildContext, Group)?` |\n| Type error on `CometChatConversations.onItemTap` | Extra `BuildContext` parameter | Signature is `Function(Conversation)?` — no BuildContext |\n| Type error on `CometChatGroupMembers.onItemTap` | Extra `BuildContext` parameter | Signature is `Function(GroupMember)?` — no BuildContext |\n\n## v5 vs v6 Drift Detection\n\nIf you see any of these in a v5 project, it's a v6 pattern that was accidentally used:\n\n| v6 Pattern (wrong in v5) | v5 Equivalent |\n|--------------------------|---------------|\n| `import 'package:flutter_bloc/flutter_bloc.dart'` | GetX — no BLoC in v5 |\n| `extends Bloc<Event, State>` | `extends GetxController` |\n| `extends Equatable` | Not used in v5 |\n| `ServiceLocator.get<T>()` | `Get.find<T>()` or let widget manage |\n| Single `cometchat_chat_uikit` with calls built-in | Separate `cometchat_calls_uikit` package |\n| Per-widget feature flags only — no `BuilderSettings` | `BuilderSettings`, `BuilderColor`, `BuilderTypography` |\n| `enableCalls: true` + `CallingConfiguration()` on UIKitSettingsBuilder | `..callingExtension = CometChatCallingExtension()` |\n\n## Verify Checklist\n\nRun through this when something isn't working:\n\n- [ ] `CometChatUIKit.init()` completes before any other CometChat call\n- [ ] `subscriptionType` set in UIKitSettingsBuilder\n- [ ] `region` is lowercase\n- [ ] Theme cached in `didChangeDependencies()`, not `build()`\n- [ ] All listeners registered with unique IDs\n- [ ] All listeners removed in `dispose()` / `onClose()`\n- [ ] `CallNavigationContext.navigatorKey` set on MaterialApp\n- [ ] `CometChatCallingExtension()` set if using calls\n- [ ] Push tokens registered after login\n- [ ] Push tokens unregistered before logout\n- [ ] ProGuard rules present for release builds\n- [ ] No v6 imports (`flutter_bloc`, `equatable`, `BlocProvider` / `BlocBuilder`)","tags":["cometchat","flutter","troubleshooting","skills","agent-skills","ai-agent","chat","claude-code","cursor","messaging","nextjs","react"],"capabilities":["skill","source-cometchat","skill-cometchat-flutter-v5-troubleshooting","topic-agent-skills","topic-ai-agent","topic-chat","topic-claude-code","topic-cometchat","topic-cursor","topic-messaging","topic-nextjs","topic-react","topic-react-native","topic-ui-kit"],"categories":["cometchat-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/cometchat/cometchat-skills/cometchat-flutter-v5-troubleshooting","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add cometchat/cometchat-skills","source_repo":"https://github.com/cometchat/cometchat-skills","install_from":"skills.sh"}},"qualityScore":"0.463","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 27 github stars · SKILL.md body (6,933 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:04:50.678Z","embedding":null,"createdAt":"2026-05-07T13:05:10.192Z","updatedAt":"2026-05-18T19:04:50.678Z","lastSeenAt":"2026-05-18T19:04:50.678Z","tsv":"'0xff':147 '26':493 'accident':612 'activ':406 'add':479,518 'alway':260 'android':466 'android.useandroidx':502 'android/app/build.gradle':495 'androidx':496,499 'anim':114 'app':53,64 'appear':338 'appid':56,62 'authent':44 'await':74 'awar':170,176 'background':419,456,464 'black':164 'bloc':627,631,751 'bloc/flutter_bloc.dart':624 'blocbuild':754 'blocprovid':753 'bright':169,175 'brightness-awar':168,174 'build':119,467,473,483,507,709,746 'buildcontext':545,550,557,562,569,576,582,589 'buildercolor':671 'builderset':669,670 'buildertypographi':672 'built':655 'built-in':654 'button':335 'cach':120,134,705 'call':48,49,80,117,317,323,334,347,359,362,385,396,414,653,659,696,730 'callback':534 'callingconfigur':675 'callingextens':343,678 'calllisten':368 'callnavigationcontext.navigatorkey':328,722 'callnavigationcontext.navigatorkey.currentcontext':440 'camera/mic':512 'camera/microphone':350 'caus':17,33,42,108,181,250,320,377,470,510,538 'ccmessages':296 'chang':128,159 'chat':650 'check':20,37,408 'checklist':681 'class':481 'cleanup':205 'cocoapod':524 'collis':270 'color':139,146 'colorpalette.neutral50':172 'colorpalette.primary':153 'colorpalette.textprimary':154 'colorpalette.white':156 'com.cometchat':482 'cometchat':2,9,25,649,658,695 'cometchat-flutter-v5-troubleshooting':1 'cometchat.sendmessage':300 'cometchatcalleventlisten':369 'cometchatcallingextens':339,344,679,726 'cometchatconversations.onitemtap':567 'cometchatgroupmembers.onitemtap':580 'cometchatgroups.onitemtap':555 'cometchatsubscriptiontype.allusers':103,287 'cometchatthemehelper.getcolorpalette':115 'cometchatuikit.init':46,690 'cometchatuikit.sendtextmessage':303 'cometchatusers.onitemtap':543 'common':21 'complet':72,76,691 'compon':123,193 'conflict':497 'context':116 'control':184,197,198,203,214,217,231 'controllertag':207,236,240 'convers':407,574 'conversationid':409 'crash':474,514 'creat':202,216,234 'dark':143,161 'dashboard':371 'datetime.now':278 'debug':8 'delet':230,238 'detect':24,594 'didchangedepend':122,137,707 'direct':301 'dispos':200,259,309,315,720 'doesn':157,325,416,437 'drift':23,593 'duplic':252,400 'enabl':458 'enablecal':673 'ensur':443 'entri':429,517 'entry-point':428 'equat':637,752 'equival':620 'err':82 'error':22,487,536,541,553,565,578 'etc':155 'eu':90 'event':247,253,305,632 'extend':630,634,636 'extra':568,581 'fail':348,484,523 'featur':665 'fire':254,298,306 'fix':43,109,182,251,295,321,378,471,511,539 'flag':131,133,666 'flutter':3,10,26,623,750 'foreground':402 'found':186 'function':435,549,561,573,586 'get.delete':228 'get.find':188,643 'get.put':190,227 'getx':178,183,625 'getxcontrol':635 'global':366 'gradle.properties':505 'grant':353 'group':563 'groupmemb':587 'handl':226,361 'handler':420 'hang':67 'hardcod':138,271 'hasn':70 'id':54,65,264,269,273,277,715 'import':621,749 'incom':322,358 'indic':282 'info.plist':516 'init':38,50,69,75 'initst':225 'instal':522,533 'instanc':215 'instead':148,304 'invalid':83 'io':449,506 'ip':461 'isfcm':388 'isn':687 'issu':13,40,106,179,248,318,375,468,508 'isvoip':389 'jank':111 'keep':477,480 'keyboard':113 'layout':105 'let':191,209,221,645 'level':372,424,434 'lifecycl':212 'listen':246,255,268,272,310,363,711,717 'load':97 'login':39,66,81,92,735 'login/components':52 'logout':392,399,740 'lookup':18,34 'low':490 'lowercas':88,703 'manag':194,211,245,647 'manual':201 'match':142,410 'materialapp':448,725 'materialapp.navigatorkey':333 'messag':96 'migrat':500 'millisecondssinceepoch':279 'minsdk':486,488,492 'mismatch':526 'miss':454,475,498,515,544,556 'mode':144,162,457,465 'multipl':213 'navig':439 'navigatorkey':444 'notif':374,381,390,401,403,415 'nscamerausagedescript':519 'nsmicrophoneusagedescript':520 'null':45,55,242,442 'onclos':316,721 'online/offline':289 'onsuccess':78 'outsid':218 'overlay':324 'packag':622,661 'paramet':546,558,570,583 'pattern':609,615 'per':663 'per-widget':662 'permiss':351,513 'permission.camera':355 'permission.microphone':357 'pnregistry.registerpnservice':386 'pnregistry.unregisterpnservice':397 'pod':521,528,532 'point':430 'pragma':426 'present':743 'proguard':476,741 'project':604 'push':373,380,731,736 'reflect':126 'region':84,86,701 'regist':267,341,365,367,384,453,712,733 'releas':472,745 'remov':132,257,261,312,313,718 'repo':529 'request':354 'rule':478,742 'run':527,682 'screen':308 'see':597 'separ':657 'servicelocator.get':642 'set':58,61,100,101,285,286,293,330,331,342,446,491,501,698,723,727 'show':327,412,418 'shown':404 'signatur':535,547,559,571,584 'silent':68,349 'singl':648 'skill' 'skill-cometchat-flutter-v5-troubleshooting' 'someth':686 'source-cometchat' 'state':633 'status':290 'string':274 'subscriptiontyp':98,102,283,291,697 'succeed':93 'symptom':15,31,41,107,180,249,319,376,469,509,537 'symptom-to-caus':14,30 'tap':436 'theme':110,127,150,704 'themeiniti':130 'throw':229 'timestamp':276 'token':151,382,387,393,451,732,737 'top':423,433 'top-level':422,432 'topic-agent-skills' 'topic-ai-agent' 'topic-chat' 'topic-claude-code' 'topic-cometchat' 'topic-cursor' 'topic-messaging' 'topic-nextjs' 'topic-react' 'topic-react-native' 'topic-ui-kit' 'transpar':165 'troubleshoot':5,29 'true':503,674 'type':281,540,552,564,577 'ui':104 'uikit':11,27,192,651,660 'uikitsettingsbuild':60,346,677,700 'uncondit':135 'uniqu':714 'unregist':395,738 'updat':530 'uppercas':85 'us':89 'use':6,87,129,145,152,171,187,206,265,275,299,302,425,613,639,729 'user':551 'v5':4,12,28,590,603,618,619,629,641 'v6':592,608,614,748 'verif':36 'verifi':19,680 'version':525 'via':77 'vm':427 'voic':459 'voip':413,450,455 'vs':591 'white':163,177 'widget':210,220,223,244,646,664 'widget-manag':243 'without':204 'work':689 'wrong':616 'xcode':463 'yet':73","prices":[{"id":"58d9ab1c-b15e-41f9-a02e-869b3dc5203d","listingId":"6ecabc7b-65c0-4a01-a06b-6edd0ae85797","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"cometchat","category":"cometchat-skills","install_from":"skills.sh"},"createdAt":"2026-05-07T13:05:10.192Z"}],"sources":[{"listingId":"6ecabc7b-65c0-4a01-a06b-6edd0ae85797","source":"github","sourceId":"cometchat/cometchat-skills/cometchat-flutter-v5-troubleshooting","sourceUrl":"https://github.com/cometchat/cometchat-skills/tree/main/skills/cometchat-flutter-v5-troubleshooting","isPrimary":false,"firstSeenAt":"2026-05-07T13:05:10.192Z","lastSeenAt":"2026-05-18T19:04:50.678Z"}],"details":{"listingId":"6ecabc7b-65c0-4a01-a06b-6edd0ae85797","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"cometchat","slug":"cometchat-flutter-v5-troubleshooting","github":{"repo":"cometchat/cometchat-skills","stars":27,"topics":["agent-skills","ai-agent","chat","claude-code","cometchat","cursor","messaging","nextjs","react","react-native","ui-kit"],"license":null,"html_url":"https://github.com/cometchat/cometchat-skills","pushed_at":"2026-05-18T05:04:24Z","description":"Add CometChat chat 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.","skill_md_sha":"c81772510049fc79e64ee6477e9cfcd9f2d441be","skill_md_path":"skills/cometchat-flutter-v5-troubleshooting/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/cometchat/cometchat-skills/tree/main/skills/cometchat-flutter-v5-troubleshooting"},"layout":"multi","source":"github","category":"cometchat-skills","frontmatter":{"name":"cometchat-flutter-v5-troubleshooting","license":"MIT","description":"Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection.","compatibility":"cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3"},"skills_sh_url":"https://skills.sh/cometchat/cometchat-skills/cometchat-flutter-v5-troubleshooting"},"updatedAt":"2026-05-18T19:04:50.678Z"}}