Troubleshooting

Most issues fall into a few buckets: the stylesheet import, host z-index, credentials (especially the JWT _id), viewport height and bundler config. Related guides: Project setup, Host app integration and FAQ.

“Cannot find module '@realtimexsco/live-chat' or its type declarations” - types didn't install correctly:

1npm ls @realtimexsco/live-chat2ls node_modules/@realtimexsco/live-chat/dist/index.d.ts

If the .d.ts is missing, reinstall (rm -rf node_modules && npm install).

A dependency (zustand, firebase, videosdk, lexical, dompurify, …) didn't install - these are regular dependencies of the package, not peers, and install automatically. Don't add Lexical or DOMPurify to your app. If one is missing, your lockfile is stale: delete it and node_modules, then reinstall.

Rich-text formatting looks wrong (no bold, lists, mentions) - make sure styles.css is imported; the Lexical theme classes are pre-compiled into it.

Chat renders completely unstyled - styles.cssisn't imported, or a stale pre-1.7 copy is cached. Older versions relied on the host's Tailwind @source; current versions ship a fully pre-compiled stylesheet. For a linked package, rebuild and reinstall.

Brand accent (buttons, links, badges) is grey/black - themeColor sets the --chat-theme* variables at runtime, but anything rendered before mount (or outside <ChatMain>) needs a fallback:

1:root {2  --chat-theme: #6366f1;3  --chat-theme-5: #6366f10D;4  --chat-theme-10: #6366f11A;5  --chat-theme-20: #6366f133;6  --chat-theme-40: #6366f166;7  --chat-theme-60: #6366f199;8}

Whole page scrolls instead of the message list - give ChatMain a height (viewportHeight) and let ancestors shrink (min-h-0).

• Modal doesn't appear - usually missing styles.css or a host sidebar z-index above the chat overlay. Inspect [data-slot="dialog-content"] - see Host app integration.
• No backdrop or wrong colours - stylesheet missing, or sub-components rendered outside <ChatMain /> (no theme provider).
• Works on one route, broken on another- that route's layout doesn't load global CSS. Move the import to the root layout's globals.css.
• Host styles changed after installing chat - styles.css adds shadcn-compatible :root fallbacks. Re-declare your tokens after the package import.

ERROR_OPERATION_IN_PROGRESS: A join request is already in progress. - @videosdk.live/react-sdk is on the wrong major. The package is built against 0.13.3; 1.x auto-joins and collides. Pin it, restart the dev server and hard-reload:

1npm ls @videosdk.live/react-sdk2npm install @videosdk.live/react-sdk@0.13.3

Video call crashes with unstable_NormalPriority (pnpm only) - add "@realtimexsco/live-chat > @videosdk.live/react-sdk" to optimizeDeps.include (see Project setup).

504 (Outdated Optimize Dep) for everything - Vite's node_modules/.vite cache went stale. Stop and restart the dev server, then hard-reload (Ctrl+Shift+R).

Recording button does nothing- only the call's host can record. RECORDING_DISABLED means the workspace setting is off (enforced server-side).

Whiteboard button missing - check whiteboardEnabled (Admin permissions) and that calling itself works.

When linking via "file:../path/to/realtimex-npm-package":

• Bundlers use the built dist/, not src/ - rebuild (npm run build, or npm run dev to watch) after every change.
• After the first link or any dependency change, reinstall in the host app too.
• Odd VideoSDK errors after a rebuild: delete the host's node_modules/.vite and restart.

Messages on the wrong side, or contacts empty - loggedUserDetails._iddoesn't match the _id in your JWT. Decode and compare:

JSON.parse(atob(token.split(".")[1]));

Requests blocked by CORS in local dev - see the dev proxy in Project setup.

• react + react-dom installed - tailwindcss is not required.
• @realtimexsco/live-chat installed (Lexical and DOMPurify come with it).
• pnpm + Vite: nested @realtimexsco/live-chat > … entries in optimizeDeps.include.
• styles.css imported once, globally.
• Chat inside a sized container, with the right viewportHeight.
• Chat modals verified above a high-z-index host sidebar.
• chat.config.ts with clientId, accessToken, loggedUserDetails (_id matching the JWT) and apiUrl ending in /api/v1.
• Next.js: "use client" and transpilePackages.
• Web push: firebase-messaging-sw.js in public/; Electron: window.desktop bridge.
• onSessionEnd wired to your sign-in screen (and refreshToken passed).
• Custom slots honor admin gates (useAdminFeatureGate).