Troubleshooting

Metro or codegen errors about a nested react-native Only one react / react-native may be in the tree. For local installs, block the package's own node_modules in Metro — see Local package / monorepo.

"Unable to resolve module" for Notifee, CallKeep or VoIP push A custom Metro config disabled transformer.allowOptionalDependencies. Re-enable it, or install the peer.

Reanimated / worklets error at startup Add react-native-worklets/plugin to babel.config.js (last), then npm run start --reset-cache.

Native module undefined after install (CallPipModule, VideosdkRPK, RtxNotifications) iOS: run pod install and check ios/Podfile.lock contains RealtimexLiveChat; make sure no react-native.config.js sets ios: null for this package. Android: clean rebuild (cd android && ./gradlew clean) and check PackageList has ScreenShareAndroidPackage.

Duplicate symbol CallPipModule / VideosdkRPK (iOS) or a duplicate CallPipPackage (Android) Remove old copies from the app target / MainApplication — the package provides them.

Rich-text composer is blank react-native-webview isn't installed or linked (pod install, rebuild). As a workaround set ui.chatRoom.composer.richText: false.

Socket stays idle apiUrl, clientId and a non-empty accessToken must be set. If the JWT has no email, call bootstrapChatSession({ email, name, hostAccessToken }). With autoConnect={false} call ensureChatSession() / bootstrapChatSession() yourself.

Socket never connects socketUrl must be the origin (https://host), not the REST URL.

Previous user's chats appear after switching accounts Call logoutChatSession() on host logout (a changed email also triggers an automatic reset).

Signed out and the chat never signs back in The server ended the session (Server-ended sessions). Silent logins with the same token stay blocked until the user signs in again or you call clearChatSessionEnd().

A conversation disappears while open The user was removed from it (NOT_A_PARTICIPANT) — expected.

Layout under the status bar / no gestures / no toasts You disabled withSafeArea / withGestureRoot / withToast without providing your own.

No in-app notification banner with withToast={false} Your toast config has no notification entry — see Toasts.

FAB hidden behind the tab bar Set ui.conversationList.fabBottomInset to the tab bar height.

Styles from one chat screen show up on another The config is global — keep ui.styles in one config (One global config).

Custom fonts not applied Register the font files natively and pass the exact family names to fonts.

Theme set in configureChat ignored The user changed appearance in settings — saved preferences win.

A feature is visible but disabled, or an action is missing Workspace settings deny it — check useAdminFeatureGate(key).disabledReason, the pin cap, group permissions and roles (Permissions & access control).

"Make admin" / "Remove" missing in group info Only the owner manages admins, and the owner can't be removed. Members can remove others only with allowMemberRemove.

Yellow-box warnings disappeared in development ChatProvider calls LogBox.ignoreAllLogs().

No pushes at all /push/config isn't configured / enabled; permission denied; Firebase files from a different project than the dashboard's; iOS: APNs key not uploaded to Firebase (dashboard status third_party_auth_error) or Push Notifications capability missing.

Pushes only while the app is open (iOS) remote-notification background mode missing, or the app delegate completes didReceiveRemoteNotification itself before React Native Firebase's handler runs.

Two banners in the foreground Your onMessage / willPresent also shows RealtimeX pushes — skip isRealtimexPush(...), or set messaging_ios_foreground_presentation_options: [] in firebase.json.

Tapping a push from the killed state only opens the app Your getInitialNotification() ran first and dropped it — forward RealtimeX ones with openRealtimexNotification.

Android ringing call doesn't show when the app is killed registerRealtimexBackgroundHandler() / handleRealtimexBackgroundMessage missing from index.js, androidFullScreenCalls not set, or Notifee not installed.

Android 14+ crash after accepting the screen-share prompt The MediaProjection foreground service is missing — check autolinking, or paste host-setup/android/AndroidManifest.snippet.xml if you disabled it.

PiP doesn't open on Home (Android) android:supportsPictureInPicture missing on MainActivity.

iOS screen share never starts App Group mismatch between app, extension and SampleHandler, or RTCScreenSharingExtension ≠ the extension bundle id.

iOS: no CallKit ring when killed / locked Dashboard Apple VoIP card not ok; voip background mode missing; CallKeep / VoIP push not installed or pod install not run; RealtimexVoipAutoSetup set to NO. The Xcode log [RealtimexVoip] … says why the bootstrap stayed off.

iOS: dashboard card says bad_device_token Build and apnsEnvironment disagree (Debug = sandbox, TestFlight / App Store = production).

iOS: Accept on the lock screen opens the app but the call never joins Camera / microphone never granted; a post-login navigation.reset dropped ActiveCallScreen; or old AppDelegate PushKit code with an unpatched CallKeep on the New Architecture — remove that code (Upgrading).

iOS: app crashes on a VoIP push / VoIP pushes stop Host PushKit code doesn't report every push to CallKit — remove it and let the pod handle PushKit.

iOS: call answered from the lock screen has no audio CallKit owns the audio session: host code must not play its own ringtone or change the AVAudioSession while CallKit rings or runs the call.

iOS: your video freezes for others in PiP / Split View Apply host-setup/patches/@videosdk.live+react-native-webrtc+0.0.22.patch; needs the voip background mode on iOS 18+, or the Apple-granted multitasking-camera entitlement on iOS 16–17.

iOS (Debug): a "Dismiss ✕" bar over the status bar after a call wakes the app Metro's "Fast Refresh disconnected" banner, never in Release.