cometchat-native-troubleshooting-50adf1— agent skill

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.

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.

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

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@latest

# 2. Install the full peer-dep set (v5 doesn't auto-install them like v4 did)
npm install @cometchat/chat-sdk-react-native \
  @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. Read the raw error. RN errors are usually specific ("Module 'X' not found in app 'Y'" is different from "TurboModuleRegistry.getEnforcing").
2. Check the dev console + native logs. For iOS: Xcode → View → Debug Area → Activate Console. For Android: adb logcat | grep -E "cometchat|CometChat|ReactNative".
3. Search the upstream docs MCP (cometchat-docs if installed).
4. Search the sample app (examples/SampleApp/ or examples/SampleAppExpo/) for a working version of the pattern the user is trying.
5. 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