> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common issues when using CometChat React UI Kit v7

## SSR Hydration Errors

### Symptom

You see a React hydration mismatch error in the console when rendering your app with a server-side rendering framework (Next.js, Remix, Astro SSR):

```
Error: Hydration failed because the initial UI does not match what was rendered on the server.
```

### Root Cause

`CometChatProvider` uses browser-only APIs (WebSocket connections, `window`, `localStorage`). When a parent component renders on the server, it produces different output than the client, causing a hydration mismatch.

### Solution

Mark the component boundary containing `CometChatProvider` as client-only. In Next.js App Router, add the `'use client'` directive at the top of the file:

```tsx theme={null}
'use client';

import { useEffect, useState } from 'react';
import { CometChatUIKit, UIKitSettingsBuilder, CometChatProvider } from '@cometchat/chat-uikit-react';

export function ChatProvider({ children }: { children: React.ReactNode }) {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return null;

  return (
    <CometChatProvider>
      {children}
    </CometChatProvider>
  );
}
```

For Astro, use a `client:only="react"` directive on the component that wraps `CometChatProvider`:

```astro theme={null}
<ChatApp client:only="react" />
```

This ensures `CometChatProvider` only renders in the browser where its required APIs are available.

***

## React StrictMode Double-Mount

### Symptom

You notice duplicate SDK event listeners firing, causing messages to appear twice or callbacks triggering multiple times during development.

### Root Cause

React StrictMode intentionally mounts, unmounts, and remounts components in development to help detect side effects that aren't properly cleaned up. If SDK listeners aren't cleaned up on unmount, the remount adds a second listener.

### Solution

All v7 hooks handle cleanup automatically. If you're writing custom hooks that attach SDK listeners, always return a cleanup function from `useEffect`:

```tsx theme={null}
import { useEffect, useId } from 'react';
import { CometChat } from '@cometchat/chat-sdk-javascript';

function useCustomMessageListener(onMessage: (msg: CometChat.BaseMessage) => void) {
  const listenerId = useId();

  useEffect(() => {
    CometChat.addMessageListener(
      listenerId,
      new CometChat.MessageListener({
        onTextMessageReceived: onMessage,
        onMediaMessageReceived: onMessage,
        onCustomMessageReceived: onMessage,
      })
    );

    // Cleanup removes the listener on unmount
    return () => {
      CometChat.removeMessageListener(listenerId);
    };
  }, [listenerId, onMessage]);
}
```

Key points:

* Use `useId()` for unique listener IDs — it's stable across StrictMode remounts within the same component instance.
* Always remove listeners in the cleanup function returned from `useEffect`.
* The built-in `useCometChatEvents` hook already handles this correctly.

***

## SDK Initialization Failures

### Symptom

The chat UI shows an error state or nothing renders. The console displays:

```
CometChat SDK initialization failed: ERR_INVALID_CREDENTIALS
```

or

```
CometChat SDK initialization failed: ERR_NETWORK
```

### Root Cause

**Invalid credentials:** The `appId`, `region`, or `authKey` passed to `UIKitSettingsBuilder` are incorrect, expired, or belong to a different environment (e.g., using production credentials in a development build).

**Network issues:** The client cannot reach CometChat's servers due to network restrictions, firewall rules, or the CometChat service being temporarily unavailable.

### Solution

Verify your credentials match your CometChat dashboard and add error handling to your init/login flow:

```tsx theme={null}
import { CometChatUIKit, UIKitSettingsBuilder } from '@cometchat/chat-uikit-react';

const settings = new UIKitSettingsBuilder()
  .setAppId(import.meta.env.VITE_COMETCHAT_APP_ID)
  .setRegion(import.meta.env.VITE_COMETCHAT_REGION)
  .setAuthKey(import.meta.env.VITE_COMETCHAT_AUTH_KEY)
  .build();

try {
  await CometChatUIKit.init(settings);
  await CometChatUIKit.login("cometchat-uid-1");
} catch (error) {
  console.error('CometChat initialization error:', error);
}
```

Checklist:

* Confirm `appId` and `region` match the values shown in your [CometChat Dashboard](https://app.cometchat.com)
* Ensure credentials are for the correct environment (development vs. production)
* Check that your network allows outbound WebSocket connections
* Verify the `authKey` has not been rotated since you last copied it

***

## Theme Not Applying

### Symptom

Components render with default styling and ignore the theme you've configured. Colors, fonts, or spacing don't match your custom theme.

### Root Cause

The theme is activated by the `data-theme` attribute on a parent element, which `CometChatProvider`'s `theme` prop sets for you. If the `theme` prop is missing — or set to a custom theme with no matching variable definitions — the theme won't apply.

### Solution

Set the `theme` prop on `CometChatProvider`:

```tsx theme={null}
import { CometChatProvider } from '@cometchat/chat-uikit-react';

function App() {
  return (
    <CometChatProvider theme="dark">
      {/* Components will use dark theme */}
    </CometChatProvider>
  );
}
```

If you're using a custom theme, make sure your CSS defines variables under a matching `[data-theme]` selector:

```css theme={null}
[data-theme="my-brand"] {
  --cometchat-primary-color: #6366f1;
  --cometchat-background-color: #0f0f23;
  --cometchat-text-color: #e2e8f0;
  --cometchat-border-color: #334155;
}
```

Then pass the custom theme name to the provider:

```tsx theme={null}
<CometChatProvider theme="my-brand">
```