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:

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

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

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

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:

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