# troubleshooting — CometChat React v7: symptom → cause → fix

The fast symptom-table for a broken integration. Each row is a REAL failure mode, baked (don't fetch docs); deeper detail is cross-linked to the sibling reference.

## The table
| Symptom (what the user sees) | Root cause | Fix |
|---|---|---|
| **Blank / empty screen, no errors** | Component rendered BEFORE `init()`+`login()` resolved, or wrong Region / env prefix so init silently fails | Gate render on `getLoggedInUser()` (`init→login→render` is invariant); verify Region matches the Dashboard app + env prefix matches the bundler. `lifecycle.md` + `setup-credentials.md`. |
| **`window is not defined` / `document is not defined`** | SSR — the kit touches browser globals during server render (Next RSC, Astro, React-Router) | Make the chat tree client-only: Next `"use client"` + `dynamic(…, { ssr:false })`; Astro `client:only="react"`; RR guard `typeof window`. `ssr.md`. |
| **Chat renders as a ~0px sliver / crammed top-left** | The container has no resolved height/width — kit components are `height:100%`/flex-fill and collapse in a content-driven box (static collapse) | Content-INDEPENDENT height **and** width: full-page `100dvh`/`100%`; embedded a fixed height or sized grid/flex cell. **Columns need height + `min-height:0` too**, not just the root. `layout.md` + `anti-patterns.md` #8. |
| **Chat is small while the list loads, then GROWS to full size** (reflow) | Box is content-driven, not pinned (ancestor chain not `height:100%`, or `min-height`/`auto`, or an unsized wrapper) — the kit fills "nothing" and grows as content arrives | Pin independent of content: `html,body,#root{height:100%;margin:0}` + `100dvh` (never `min-height`/`auto`) + `min-height:0` columns; let the kit's own `loadingView`/`emptyView` fill the pinned box. `layout.md` (AUDIT-023). |
| **Snake_case tokens** (`group_info`, `add_members`) instead of labels | Localization key MISS — `getLocalizedString` returns the raw key; v7 namespaces sample strings under `sample_` so v6 keys miss | Map to the v7 key (`group_info`→`sample_group_info`) or the INSTANCE method `CometChatLocalize.getSharedInstance()?.addTranslation(...)`; look up the EXACT key in the kit source / docs — never guess. `i18n-rtl-a11y.md` + migration §7. |
| **Usernames centered / conversations header keeps growing** | Host GLOBAL CSS leaking into the `.cometchat` subtree (global `text-align:center`, a centering reset, or `flex:1` on a kit ancestor — often Tailwind base) | Scope global styles away from the kit root; never override the kit's internal classes (its defaults are correct). Customize via theme vars + view slots only. `anti-patterns.md` #12. |
| **Kit overlays (menus, emoji, call screen) clipped / mis-positioned** | A `transform`/`filter`/`backdrop-filter` on a wrapper above the kit traps its `position:fixed` overlays | Remove the transform/filter from the chat wrapper; animate `left`/`right`/width instead. `anti-patterns.md` #8/#11. |
| **`version_conflict` on `detect`, or two kits behaving oddly** | The project declares a non-v7 kit major (v5/v6), or two cohorts at once | STOP. Reconcile: upgrade to v7 (migration skill for v6→v7), load the matching-version skills, or remove the extra cohort. Never mix majors. `RULES.md`. |
| **`login()` fails / "user not found"** | Logging in a UID that doesn't exist (a guessed sample like `superhero1`, not seeded) | Use a UID that EXISTS: ask, or Dashboard → Users (fresh apps seed `cometchat-uid-1`…); create one if none fits. Prod → per-user auth token + `loginWithAuthToken`. `setup-credentials.md` §6. |
| **Roster lists render every row TWICE + ~30 "duplicate key" errors** (dev only) | React **StrictMode** (default in fresh Vite) double-invokes effects; roster drop-ins `CometChatUsers`/`CometChatGroups`/`CometChatGroupMembers` double-append (kit de-dupe gap; `CometChatConversations` unaffected). Dev-only. | A StrictMode DEV artifact — gone in `vite build`/prod. Do NOT remove StrictMode to "fix" it; verify the roster in a prod build. Kit issue (report upstream). AUDIT-062/065. |
| **`TS6133` "declared but never read" on a `CometChat` import** | The `CometChat` SDK is an ambient global — importing the namespace only for TYPE use trips `noUnusedLocals`+`verbatimModuleSyntax` (Vite React-TS) | Import only for VALUE use (`instanceof CometChat.User`, `new CometChat.*RequestBuilder`). Type-only → reference `CometChat.User`/`.Group` with NO import (resolves ambiently). `dependencies.md` (AUDIT-007). |
| **StrictMode logs a double init / double login** (dev) | React 18 StrictMode double-invokes effects; an unguarded `init()`/`login()` runs twice | Guard with an init-once ref + a concurrent-login guard (`ensureLoggedIn`). `lifecycle.md`. |
| **Theme ignores the OS dark/light setting** | Kit defaults to `light`, no `theme="system"` | Sync `CometChatProvider theme=` to `prefers-color-scheme` yourself. `theming.md` (AUDIT-004). |
| **A default-on control does nothing** (search filters nothing, "Reply in Thread" no-ops) | The drop-in renders a live-looking affordance that's INERT until the host wires it (`needs_stitching`) | Wire the destination (`onSearchBarClicked`→`CometChatSearch`; `onThreadRepliesClick`→thread) OR hide it (`showSearchBar={false}`/`hideReplyInThreadOption`). Never dead-end. Features skill. |
| **Search wired but returns nothing (HTTP 402)** | `CometChatSearch`'s server call returns `402 Payment Required` until Search is enabled on the plan/Dashboard | TELL the user: wiring alone yields nothing — enable Search in the Dashboard / upgrade. `features.json` `message-search`. |
| **Call buttons hidden / calls never ring** | Calling not enabled, or the calls SDK isn't installed | Install `@cometchat/calls-sdk-javascript@5` (not bundled) AND turn calling ON: `uiKit:{ callsSDK:{} }` in `CometChatUIKit.initFromSettings`. Both required; groups don't ring (join model). Calls skill. |

## When it's NOT in the table
- **Prop/signature question** → fetch the component's `.md` twin via `docs-map.md`; never read `.d.ts` or answer from memory.
- **A feature renders empty** → the extension likely isn't enabled in the Dashboard (features skill "Verify it works").
- **Still stuck** → check the console + network tab (a `4xx` on a CometChat endpoint = auth/plan/config, not a code bug), confirm App ID/Region/Auth Key in the env, and re-verify the detected framework/bundler + prefix by reading the project.