> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-platform-docs-release.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`) during initialization. When the 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 { CometChatProvider } from '@cometchat/chat-uikit-react';
import '@cometchat/chat-uikit-react/styles';

export function ChatProvider({ children }: { children: React.ReactNode }) {
  return (
    <CometChatProvider
      appId="YOUR_APP_ID"
      region="YOUR_REGION"
      authKey="YOUR_AUTH_KEY"
    >
      {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 `useSDKEvents` 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 `CometChatProvider` 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 use the `onError` callback to surface initialization issues:

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

function App() {
  return (
    <CometChatProvider
      appId={import.meta.env.VITE_COMETCHAT_APP_ID}
      region={import.meta.env.VITE_COMETCHAT_REGION}
      authKey={import.meta.env.VITE_COMETCHAT_AUTH_KEY}
      onError={(error) => {
        console.error('CometChat initialization error:', error);
      }}
    >
      {/* Your chat UI */}
    </CometChatProvider>
  );
}
```

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 system relies on two things working together:

1. The CSS styles file being imported (provides the CSS custom property declarations)
2. The `data-theme` attribute being set on a parent element (activates theme-specific variable values)

If either is missing, the theme won't apply.

### Solution

Ensure both the CSS import and the `theme` prop are present:

```tsx theme={null}
// 1. Import the styles entry point (required for CSS custom properties)
import '@cometchat/chat-uikit-react/styles';

// 2. Set the theme via CometChatProvider
import { CometChatProvider } from '@cometchat/chat-uikit-react';

function App() {
  return (
    <CometChatProvider
      appId="YOUR_APP_ID"
      region="YOUR_REGION"
      authKey="YOUR_AUTH_KEY"
      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" /* ...other props */>
```

***

## Missing CSS Imports

### Symptom

Components render as unstyled HTML elements — no backgrounds, no spacing, no borders. The layout is broken and elements stack vertically without proper structure.

### Root Cause

The UI Kit's styles are distributed as a separate CSS entry point. Without importing it, none of the CSS custom properties or component styles are available in the document.

### Solution

Add the styles import at your application's entry point, before any CometChat components render:

```tsx theme={null}
// main.tsx or App.tsx — import styles at the top level
import '@cometchat/chat-uikit-react/styles';
import { CometChatProvider } from '@cometchat/chat-uikit-react';

function App() {
  return (
    <CometChatProvider
      appId="YOUR_APP_ID"
      region="YOUR_REGION"
      authKey="YOUR_AUTH_KEY"
    >
      {/* Components are now styled */}
    </CometChatProvider>
  );
}
```

For Next.js, add the import in your root layout:

```tsx theme={null}
// app/layout.tsx
import '@cometchat/chat-uikit-react/styles';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

The import path `@cometchat/chat-uikit-react/styles` maps to the `"./styles"` export in the package's exports map, which resolves to the compiled CSS file containing all component styles and theme variables.