Troubleshooting - CometChat Docs

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:

'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:

<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:

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

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:

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
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:

The CSS styles file being imported (provides the CSS custom property declarations)
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:

// 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:

[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:

<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:

// 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:

// 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.

​SSR Hydration Errors

​Symptom

​Root Cause

​Solution

​React StrictMode Double-Mount

​Symptom

​Root Cause

​Solution

​SDK Initialization Failures

​Symptom

​Root Cause

​Solution

​Theme Not Applying

​Symptom

​Root Cause

​Solution

​Missing CSS Imports

​Symptom

​Root Cause

​Solution

SSR Hydration Errors

Symptom

Root Cause

Solution

React StrictMode Double-Mount

Symptom

Root Cause

Solution

SDK Initialization Failures

Symptom

Root Cause

Solution

Theme Not Applying

Symptom

Root Cause

Solution

Missing CSS Imports

Symptom

Root Cause

Solution