Cometchat Native Troubleshooting

Purpose

Teaches Claude how to diagnose and fix CometChat React Native integration failures. Covers every category of failure I've seen across Expo + bare RN, with an up-front triage flow so Claude asks the right questions before assuming a fix.

Read cometchat-native-core first — most "why doesn't this work" issues trace to the init/login/wrapper chain explained there.

Ground truth: docs/ui-kit/react-native/troubleshooting.mdx, apple-privacy-manifest-guide.mdx, upgrading-from-v4.mdx, and first-hand failure modes from real integrations. Official docs: https://www.cometchat.com/docs/ui-kit/react-native/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP).

1. Triage — read project state before guessing

When the user reports a problem, gather facts before proposing a fix. Ask + run these first:

1a. Which framework?

# Expo or bare?
grep -E '"expo":|"expo-router":' package.json
ls -d ios android 2>/dev/null   # bare RN has these dirs at root
ls app.json app.config.js 2>/dev/null

• expo in dependencies + no ios/android folders → Expo managed → route to cometchat-native-expo-patterns
• ios/ + android/ folders at root → bare RN → route to cometchat-native-bare-patterns
• Both (expo + ios/android) → bare-after-prebuild. Treat as bare.

1b. Is the wrapper chain correct?

# Confirm four wrappers in entry file
grep -E "GestureHandlerRootView|SafeAreaProvider|CometChatThemeProvider|CometChatProvider" \
  App.tsx index.js index.ts app/_layout.tsx 2>/dev/null

If any are missing, that's almost certainly the cause. See cometchat-native-core § 3.

1c. Is react-native-gesture-handler imported first?

# Must be line 1 (or 2 with a shebang) of entry
head -5 index.js index.ts App.tsx app/_layout.tsx 2>/dev/null

If the import is missing or below React, swipe gestures and bottom sheets silently break — often only in release builds.

1d. Is init complete before login?

grep -A 10 "CometChatUIKit.init" src/providers/CometChatProvider.tsx 2>/dev/null

Look for the init-then-login sequence with an await or module-level initialized flag. Fire-and-forget init is a common cause of "components don't render."

1e. Pod install state (iOS)

ls ios/Pods/ | head -5 2>/dev/null       # should list dozens of pods
cat ios/Podfile.lock | head -3 2>/dev/null

If ios/Pods/ is missing or sparse, native modules aren't linked. cd ios && pod install && cd .. is the fix.

1f. Package deps

# Check the full UI Kit peer-dep set is installed
for dep in \
  @cometchat/chat-sdk-react-native \
  @cometchat/chat-uikit-react-native \
  react-native-gesture-handler \
  react-native-safe-area-context \
  react-native-svg \
  @react-native-async-storage/async-storage; do
  node -e "try{require.resolve('$dep'); console.log('✓ $dep')}catch(e){console.log('✗ MISSING: $dep')}"
done

Missing peer deps → install + pod install (bare) or expo install (Expo) + rebuild.

⚠️ --legacy-peer-deps silently DROPS peers. If the project installed with npm install --legacy-peer-deps (common to dodge RN peer-range conflicts), npm skips unmet peer deps instead of erroring — you get a "successful" install with react-native-svg / gesture-handler / safe-area-context / async-storage missing, then a runtime crash. Re-run the check above after any --legacy-peer-deps install and install the missing ones explicitly. ⚠️ @cometchat/calls-lib-webrtc is Cloudsmith-only — NOT on npm (npm view @cometchat/calls-lib-webrtc → 404, verified). If a calls install fails resolving it, add the Cloudsmith tarball/registry per cometchat-native-calls; a plain npm install @cometchat/calls-lib-webrtc will never work.

2. Symptom → fix lookup tables

Quick-reference tables. Work through in order; if none match, drop into § 3 deep-dives.

2a. Initialization + login

2b. Gesture handler + wrapper chain

2c. iOS build failures

2d. Android build failures

2e. Metro / JS runtime

2f. Theming

2g. Components

2h. Calling

2i. Extensions

2j. AI features

2k. Localization

2l. Events

2m. Production / auth tokens

3. Deep dives on common failures

3a. "The most common 'why is my chat blank' bug"

CometChat components fill 100% of their parent's height. If the parent has no bounded height, the components render at 0px and look empty.

Diagnostic:

grep -B5 -A5 "CometChatMessageList\|CometChatConversations" src/**/*.tsx | grep -B2 -A2 "style"

Look for the message list's parent. One of these must be true:

• Parent has flex: 1
• Parent has an explicit height: N
• Parent is a flex column with the list getting flex: 1

Broken example:

<ScrollView>
  <CometChatMessageList user={user} />   {/* ← ScrollView doesn't constrain height */}
</ScrollView>

Fixed:

<View style={{ flex: 1 }}>
  <CometChatMessageList user={user} hideReplyInThreadOption />
</View>

3b. Apple Privacy Manifest rejection (ITMS-91053)

Apple's App Store Connect rejects RN apps that use certain APIs without declaring them in PrivacyInfo.xcprivacy. The CometChat kit (through React Native + react-native-video) triggers 4 of these APIs.

Full manifest content is in cometchat-native-bare-patterns § 2c. Required reason codes:

If the user's rejection email lists OTHER API categories, their app uses additional Apple APIs through other SDKs (analytics, crash reporters, etc.). Add those codes too — the CometChat-specific 4 aren't exhaustive for all apps.

After updating:

1. cd ios && pod install && cd ..
2. Rebuild the archive
3. Resubmit

3bb. react-native-document-picker build failure on RN 0.85+ (F70)

Symptom: Android debug build fails with a hard Java compile error inside react-native-document-picker's source — typically cannot find symbol class GuardedResultAsyncTask.

Root cause: react-native-document-picker references GuardedResultAsyncTask, which React Native removed from its Android internals in 0.85. The package is unmaintained — the last useful release predates RN 0.85.

Fix: uninstall it and switch to a maintained alternative if document picking is needed.

# Uninstall the broken package
npm uninstall react-native-document-picker

# For Expo apps — official maintained pick
npx expo install expo-document-picker

# For bare RN — maintained community fork
npm install @react-native-documents/picker

cometchat verify flags this combination automatically (rn_doc_picker_compat check) — runs as part of every verify since v4.3.0.

3bc. Cannot read property 'CometChatThemeProvider' of undefined on bare RN (F78 — chat-sdk 4.0.22 packaging regression)

Symptom (bare RN only): the app builds cleanly (BUILD SUCCESSFUL) but crashes at JS startup with TypeError: Cannot read property 'CometChatThemeProvider' of undefined. The error often links to RN's own AsyncStorage troubleshooting text ("Make sure your project's package.json depends on @react-native-async-storage/async-storage…").

This is NOT the §3b Maven-repo build failure — that one fails the Gradle build. F78 builds fine, then crashes at runtime.

Root cause (confirmed): @cometchat/chat-sdk-react-native 4.0.22 declares react, react-native@0.64.2, and @react-native-async-storage/async-storage@^1.13.4 as hard dependencies (4.0.21 had none). npm therefore installs nested duplicate copies inside the SDK:

node_modules/@cometchat/chat-sdk-react-native/node_modules/
  ├── react-native/               → 0.64.2   (duplicate of your app's 0.85.x)
  └── @react-native-async-storage/async-storage/  → 1.24.0

Two react-native copies = two native-module registries. The SDK's persistence code resolves AsyncStorage against its nested 1.24.0 copy, whose native module isn't the one your app autolinked → RCTAsyncStorage not found → the kit's theme module throws during evaluation → CometChatThemeProvider ends up undefined. Expo is unaffected because its resolver dedupes react-native to a single copy; bare RN installs the nested copy.

Confirm you're hit by it:

ls node_modules/@cometchat/chat-sdk-react-native/node_modules/react-native/package.json && echo "F78: nested RN present"

Fix — pick one (both verified to remove the nested install):

1. npm overrides (keep chat-sdk 4.0.22) — add to the app's package.json, then reinstall:

   "overrides": {
     "@cometchat/chat-sdk-react-native": {
       "react": "$react",
       "react-native": "$react-native",
       "@react-native-async-storage/async-storage": "$@react-native-async-storage/async-storage"
     }
   }
   

   yarn uses the equivalent top-level resolutions.
2. Pin the known-good SDK: npm i @cometchat/chat-sdk-react-native@4.0.21 (zero deps → no nesting).
3. Prefer Expo for greenfield — the Expo cohort is fresh-validated and never hits this.

After applying (1) or (2): rm -rf node_modules && npm install, then verify the nested react-native is gone with the ls check above. Tried and confirmed NOT to fix it: downgrading async-storage, newArchEnabled=false, clean rebuild, Metro --reset-cache — none address the duplicate-RN root cause.

The permanent fix is SDK-side (move react/react-native to peerDependencies) — tracked in ENG-35653.

3c. Metro cache issues (post-dep-install "not found" errors)

Happens when you npm install a native module and Metro's bundler still has the old module graph cached.

# Full reset
watchman watch-del-all 2>/dev/null          # watchman (if installed)
rm -rf $TMPDIR/metro-*                       # Metro cache on macOS
rm -rf $TMPDIR/haste-map-*                   # Haste cache on macOS
rm -rf node_modules
npm install
cd ios && pod install && cd ..               # iOS only
npx react-native start --reset-cache         # bare
# OR for Expo:
npx expo start --clear

If the error persists after a clean cache + pod install, the native module isn't autolinked. Check react-native.config.js for exclusions.

3d. "App crashes on first launch" — entry file order

index.js MUST have import "react-native-gesture-handler" as line 1. Not line 2. Not after a // comment. Not after a "use strict". Literally line 1.

Wrong:

import React from "react";              // ← line 1
import "react-native-gesture-handler";  // ← line 2 — TOO LATE

Right:

import "react-native-gesture-handler";  // ← line 1
import React from "react";

For Expo Router, the same rule applies to app/_layout.tsx.

3e. Push notification issues

Push setup is covered end-to-end in cometchat-native-push. That skill has:

• § 3 APNs p8 setup (Apple Developer portal)
• § 4 FCM setup (Firebase project + service account)
• § 5 CometChat dashboard provider upload (dev + prod for iOS)
• § 7 Client registration with CometChatNotifications.registerPushToken(token, platform, providerId) (the correct API — not CometChat.registerTokenForPushNotification)
• § 9 Foreground display + tap-to-deep-link handlers
• § 12 Troubleshooting table mapping symptoms to fixes (production APNs cert missing, token registered before login, Expo Go can't receive push, etc.)

When diagnosing a push issue, route the user to cometchat-native-push § 12 rather than re-triaging here.

4. v4 → v5 upgrade gotchas

If the user is upgrading from @cometchat/chat-uikit-react-native@4, these are the common breakages. Full migration guide: docs/upgrading-from-v4.mdx.

Upgrade sequence

# 1. Update the main kit
npm install @cometchat/chat-uikit-react-native@^5

# 2. Install the full peer-dep set (v5 doesn't auto-install them like v4 did)
npm install @cometchat/chat-sdk-react-native@^4 \
  @react-native-async-storage/async-storage \
  @react-native-clipboard/clipboard \
  @react-native-community/datetimepicker \
  react-native-gesture-handler react-native-localize \
  react-native-safe-area-context react-native-svg \
  react-native-video dayjs punycode

# 3. iOS
cd ios && pod install && cd ..

# 4. Android — add the local Maven repo for async-storage
#    (see cometchat-native-bare-patterns § 3b)

# 5. Entry file — add `import "react-native-gesture-handler"` as line 1
#    (new requirement in v5)

# 6. Replace `<CometChatContext>` with the 4-wrapper chain
#    (see cometchat-native-core § 3)

# 7. Split composite components — e.g. `<CometChatConversationsWithMessages>`
#    becomes two screens with navigation

# 8. Rename `onClick*` → `onPress*` throughout

# 9. Replace `Palette` → theme tokens

# 10. Rebuild + test

5. Escalation — when the above doesn't solve it

If none of the lookup tables or deep dives apply:

1. Run cometchat doctor (the structured first pass — combines detect + info + verify + known-issue matching). Start here; it often pinpoints the layer (state / drift / env / deps) before you read logs.
2. Read the raw error. RN errors are usually specific ("Module 'X' not found in app 'Y'" is different from "TurboModuleRegistry.getEnforcing").
3. Check the dev console + native logs. For iOS: Xcode → View → Debug Area → Activate Console. For Android: adb logcat | grep -E "cometchat|CometChat|ReactNative".
4. Search the upstream docs MCP (cometchat-docs if installed).
5. Search the sample app (examples/SampleApp/ or examples/SampleAppExpo/) for a working version of the pattern the user is trying.
6. If the issue is a kit bug, file at https://github.com/cometchat/cometchat-uikit-react-native/issues with a minimal repro.

6. Hard rules (diagnostic best-practice)

1. Don't assume — triage first. § 1 gets the framework, wrapper chain, pod state, and dep list before proposing a fix. A "I don't see messages" could be 10 different things.
2. Don't suggest "try reinstalling node_modules" as a first step. It's rarely the actual fix and it takes minutes; check the entry file, wrapper chain, and pod state first.
3. Always verify against the ground-truth doc (troubleshooting.mdx). If a user's symptom matches a table row, use the doc's fix verbatim — don't paraphrase.
4. Never guess a fix that requires code changes without first gathering facts. Changing code based on a wrong hypothesis wastes user time.
5. When recommending a rebuild, say why + what to rebuild. "pod install + rebuild iOS" is more useful than "try rebuilding."
6. If a symptom matches the Apple Privacy Manifest rejection, always paste the full 4-code XML. Don't describe it; show it.

Skill routing reference