fix: bug bashing ChannelList + Channel (#2474, #2441, #2393) (#3227)

### 🎯 Goal

Fixes three Tier‑1 issues from the bug‑bash triage. Each is an
independent fix kept as its own self‑contained commit (with tests):

- **Closes #2474** — a `message.new` for a not‑yet‑watched channel
inserts an uninitialized channel into the list; rendering it called
`channel.muteStatus()`, which throws `"hasn't been initialized yet"` and
**crashed the whole app**.
- **Closes #2441** — `ChannelList` issued a `queryChannel`
(`channel.watch()`) for **every** `notification.message_new`, even when
the result was discarded, exhausting the rate limit during bulk channel
activity.
- **Closes #2393** — once the shared client is disconnected,
`channel.lastRead()` (called during render in
`useCreateChannelStateContext`) throws `"You can't use a channel after
client.disconnect() was called"`, **crashing the render** with no error
boundary to catch it.

> **#2599 — fixed via the `stream-chat` upstream fix + this PR's
dependency bump.** An earlier `stopWatching`-on-removal attempt here was
implemented and then reverted: it did **not** make removal durable.
`channel.stopWatching()` does not evict the channel from
`client.activeChannels`, so a reconnect (`recoverState` re-watches every
active channel) or a queued/in-flight `message.new` re-added the removed
channel — the exact reported symptom. The real fix evicts
`activeChannels[cid]` on `notification.removed_from_channel` (mirroring
the existing `channel.deleted` handling); it shipped in
**`stream-chat@9.49.0`** (GetStream/stream-chat-js#1788). This PR bumps
the `stream-chat` requirement to `^9.49.0` and adds a regression test —
with the bump in place, `ChannelList` removal is durable and the test
passes.

### 🛠 Implementation details

**#2474 — `fix(ChannelListItem): guard muteStatus against an
uninitialized/disconnected channel`**
- `useIsChannelMuted` reads the mute status through a helper that calls
`channel.muteStatus()` only when the channel is initialized **and not
disconnected**, falling back to a not‑muted status otherwise.
`muteStatus()` throws on an uninitialized channel (`#2474`) and also
after the client disconnects — via `channel.getClient()` — even though
the channel stays initialized (the #2393 failure class on the
channel‑list path).
- The mute‑update subscription now depends on `[channel, client]` and
cleans up via the `unsubscribe` handle returned by `client.on()`. It
previously depended on `[muted]`, so it re‑subscribed on its own output
and could capture a stale channel.

**#2441 — `fix(ChannelList): do not query unfiltered channels on
notification.message_new`**
- Moved the `allowNewMessagesFromUnfilteredChannels` guard **before**
the `getChannel()` call in `handleNotificationMessageNew`, so the flag
actually suppresses the per‑event `watch()` instead of querying first
and throwing the result away. Behaviour with the flag enabled is
unchanged.

**#2393 — `fix(Channel): guard channel methods against a disconnected
client`**
- Guarded `channel.lastRead()` in `useCreateChannelStateContext` with
`!channel.disconnected` so a disconnect while the channel is mounted
does not crash the render.
- `loadMore` now early‑returns when `channel.disconnected`, mirroring
the existing `markRead` guard, to avoid a doomed pagination query.
- Note: the shared‑client race cannot be fully eliminated (the existing
`try/catch` backstops on the async paths remain); this removes the
uncaught **render‑time** crash, which is the part with no safety net.

**#2599 — `fix(deps): require stream-chat ^9.49.0 to evict removed
channels`**
- Bumped `stream-chat` to `^9.49.0` in `peerDependencies` and
`devDependencies`. No `ChannelList` runtime change is required: the
existing `handleNotificationRemovedFromChannel` removes the channel from
the list, and `stream-chat@9.49.0` now evicts it from
`client.activeChannels`, so `recoverState()` won't re‑watch it on
reconnect. The two compose into durable removal.

**Tests** — added test‑first (each test was confirmed to fail before the
fix):
- `useIsChannelMuted` does not throw on an uninitialized channel, nor on
an initialized‑but‑disconnected channel.
- `notification.message_new` does not call `watch()` when
`allowNewMessagesFromUnfilteredChannels={false}`.
- rendering does not crash when the client disconnects while the channel
is mounted.
- `loadMore` does not query when the client is disconnected.
- **#2599:** `notification.removed_from_channel` evicts the channel from
`client.activeChannels` (so reconnect cannot re‑watch it). Verified
red→green — red on `stream-chat@9.47.0`, green after the `^9.49.0` bump.

Verification: `yarn test` (full suite — 2589 passing, incl. ChannelList,
ChannelListItem, Channel, MessageList, Thread), `yarn types`, and ESLint
(`--max-warnings 0`) all clean. #2474, #2441 and #2393 were additionally
confirmed in a real browser against the example app; the #2599
regression test passes against the bumped `stream-chat@9.49.0`.

### 🎨 UI Changes

None — these are crash / correctness / rate‑limit fixes in `ChannelList`
and `Channel` event handling, with no visual changes.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Fixed message-new handling when unfiltered channels aren’t allowed so
unlisted/unqueried channels aren’t watched or added to the list.
* Made mute status lookups safe when a channel isn’t initialized or is
disconnected.
* Prevented pagination and last-read handling from running while the
client/channel is disconnected to avoid crashes.

* **Tests**
* Added coverage for message-new filtering with unfiltered channels
disabled.
  * Expanded mute hook tests for uninitialized and disconnected cases.
  * Added disconnected-client scenarios for rendering and pagination.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: oliverlaz

examples/tutorial/package.json

@@ -16,7 +16,7 @@
     "emoji-mart": "^5.6.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "stream-chat": "^9.47.0",
+    "stream-chat": "^9.49.0",
     "stream-chat-react": "workspace:^"
   },
   "devDependencies": {

examples/vite/package.json

@@ -16,7 +16,7 @@
     "modern-normalize": "^3.0.1",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "stream-chat": "^9.47.0",
+    "stream-chat": "^9.49.0",
     "stream-chat-react": "workspace:^"
   },
   "devDependencies": {

package.json

@@ -111,7 +111,7 @@
     "modern-normalize": "^3.0.1",
     "react": "^19.0.0 || ^18.0.0 || ^17.0.0",
     "react-dom": "^19.0.0 || ^18.0.0 || ^17.0.0",
-    "stream-chat": "^9.47.0"
+    "stream-chat": "^9.49.0"
   },
   "peerDependenciesMeta": {
     "@breezystack/lamejs": {
@@ -181,7 +181,7 @@
     "react-dom": "^19.2.6",
     "sass": "^1.100.0",
     "semantic-release": "^25.0.3",
-    "stream-chat": "^9.47.0",
+    "stream-chat": "^9.49.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.4",
     "vite": "^8.0.14",

src/components/Channel/Channel.tsx

@@ -602,6 +602,7 @@ const ChannelInner = (
 
   const loadMore = async (limit = DEFAULT_NEXT_CHANNEL_PAGE_SIZE) => {
     if (
+      channel.disconnected ||
       !online.current ||
       !window.navigator.onLine ||
       !channel.state.messagePagination.hasPrev

src/components/Channel/__tests__/Channel.test.tsx

@@ -24,6 +24,7 @@ import { ChatProvider, useChatContext } from '../../../context/ChatContext';
 import { useComponentContext } from '../../../context/ComponentContext';
 import {
   dispatchChannelTruncatedEvent,
+  dispatchConnectionChangedEvent,
   generateChannel,
   generateFileAttachment,
   generateMember,
@@ -779,6 +780,47 @@ describe('Channel', () => {
     await waitFor(() => expect(watchSpy).toHaveBeenCalledTimes(1));
   });
 
+  describe('disconnected client (#2393)', () => {
+    it('does not crash rendering when the client disconnects while the channel is mounted', async () => {
+      let ctx: ChannelStateContextValue | undefined;
+      await renderComponent({ channel, chatClient }, (c) => {
+        ctx = c;
+      });
+
+      // the channel is initialized; the shared client then disconnects
+      channel.disconnected = true;
+
+      // a re-render that reads channel state must not throw
+      // (channel.lastRead() throws once the client is disconnected)
+      await act(async () => {
+        dispatchConnectionChangedEvent(chatClient, false);
+        await Promise.resolve();
+      });
+
+      expect(ctx).toBeDefined();
+      expect(ctx?.error).toBeNull();
+    });
+
+    it('does not paginate (query) when the client is disconnected', async () => {
+      let loadMore: ChannelActionContextValue['loadMore'] | undefined;
+      await renderComponent(
+        { channel, channelQueryOptions: { messages: { limit: 25 } }, chatClient },
+        (c) => {
+          loadMore = c.loadMore;
+        },
+      );
+
+      const querySpy = vi.spyOn(channel, 'query');
+      channel.disconnected = true;
+
+      await act(async () => {
+        await loadMore?.();
+      });
+
+      expect(querySpy).not.toHaveBeenCalled();
+    });
+  });
+
   describe('Children that consume the contexts set in Channel', () => {
     it('should be able to open threads', async () => {
       const threadMessage = messages[0];

src/components/Channel/hooks/useCreateChannelStateContext.ts

@@ -44,7 +44,11 @@ export const useCreateChannelStateContext = (
   } = value;
 
   const channelId = channel.cid;
-  const lastRead = channel.initialized && channel.lastRead()?.getTime();
+  // `channel.lastRead()` reaches `channel.getClient()`, which throws once the
+  // client has been disconnected. Guard against it so a disconnect while the
+  // channel is mounted does not crash the render (#2393).
+  const lastRead =
+    channel.initialized && !channel.disconnected && channel.lastRead()?.getTime();
   const membersLength = Object.keys(members || []).length;
   const notificationsLength = notifications.length;
   const readUsers = Object.values(read);

src/components/ChannelList/__tests__/ChannelList.test.tsx

@@ -1254,6 +1254,56 @@ describe('ChannelList', () => {
         const results = await axe(container);
         expect(results).toHaveNoViolations();
       });
+
+      it('does not query (watch) the channel when allowNewMessagesFromUnfilteredChannels is false (#2441)', async () => {
+        useMockedApis(chatClient, [queryChannelsApi([testChannel1, testChannel2])]);
+
+        const { getByRole, queryByTestId } = await render(
+          <Chat client={chatClient}>
+            <WithComponents
+              overrides={{
+                ChannelListItemUI: ChannelPreviewComponent,
+                ChannelListUI: ChannelListComponent,
+              }}
+            >
+              <ChannelList
+                allowNewMessagesFromUnfilteredChannels={false}
+                filters={{}}
+                options={{
+                  limit: 25,
+                  message_limit: 25,
+                  presence: true,
+                  state: true,
+                  watch: true,
+                }}
+              />
+            </WithComponents>
+          </Chat>,
+        );
+
+        await waitFor(() => {
+          expect(getByRole('list')).toBeInTheDocument();
+        });
+
+        // getChannel() resolves `client.channel(type, id)` to this cached
+        // instance, so spying on its watch() reveals whether a queryChannel was
+        // issued for an unfiltered channel.
+        const unlistedChannel = chatClient.channel(
+          testChannel3.channel.type,
+          testChannel3.channel.id,
+        );
+        const watchSpy = vi
+          .spyOn(unlistedChannel, 'watch')
+          .mockResolvedValue(fromPartial({}));
+
+        await act(async () => {
+          dispatchNotificationMessageNewEvent(chatClient, testChannel3.channel);
+          await Promise.resolve();
+        });
+
+        expect(watchSpy).not.toHaveBeenCalled();
+        expect(queryByTestId(testChannel3.channel.id)).not.toBeInTheDocument();
+      });
     });
 
     describe('notification.added_to_channel', () => {
@@ -1419,6 +1469,47 @@ describe('ChannelList', () => {
         const results = await axe(container);
         expect(results).toHaveNoViolations();
       });
+
+      // Regression: #2599. Removing the current user from a channel must evict it
+      // from `client.activeChannels`. Otherwise the channel lingers there and, on
+      // reconnect, `recoverState()` re-watches it (`recoverStateOnReconnect` defaults
+      // to `true`, so `usePaginatedChannels` does not re-query and relies on core
+      // recovery) - channel events then resume and the list resurrects it. The
+      // eviction itself lives in stream-chat core (`StreamChat._handleClientEvent`);
+      // this test guards that the behaviour ChannelList depends on stays in place.
+      it('evicts the removed channel from client.activeChannels so reconnect cannot re-watch it (#2599)', async () => {
+        const { getByRole, getByTestId } = await render(
+          <Chat client={chatClient}>
+            <WithComponents
+              overrides={{
+                ChannelListItemUI: ChannelPreviewComponent,
+                ChannelListUI: ChannelListComponent,
+              }}
+            >
+              <ChannelList {...channelListProps} />
+            </WithComponents>
+          </Chat>,
+        );
+        await waitFor(() => {
+          expect(getByRole('list')).toBeInTheDocument();
+        });
+
+        const { cid } = testChannel3.channel;
+        const removedNode = getByTestId(testChannel3.channel.id);
+        // precondition: the loaded channel is tracked by the client
+        expect(chatClient.activeChannels[cid]).toBeDefined();
+
+        act(() =>
+          dispatchNotificationRemovedFromChannel(chatClient, testChannel3.channel),
+        );
+
+        await waitFor(() => {
+          expect(removedNode).not.toBeInTheDocument();
+        });
+        // the channel must no longer be tracked, otherwise `recoverState()` would
+        // re-watch it on the next reconnect and bring it back into the list
+        expect(chatClient.activeChannels[cid]).toBeUndefined();
+      });
     });
 
     describe('channel.updated', () => {

src/components/ChannelList/hooks/useChannelListShape.ts

@@ -163,6 +163,15 @@ export const useChannelListShapeDefaults = () => {
         return;
       }
 
+      // Bail out before querying the channel: if new messages from unfiltered
+      // channels are not allowed, this handler would discard the result anyway.
+      // Querying first issued a `channel.watch()` (queryChannel) for every
+      // `notification.message_new`, which could exhaust the rate limit when many
+      // such events arrive at once (#2441).
+      if (!allowNewMessagesFromUnfilteredChannels) {
+        return;
+      }
+
       const channel = await getChannel({
         client,
         id: event.channel.id,
@@ -174,10 +183,6 @@ export const useChannelListShapeDefaults = () => {
         return;
       }
 
-      if (!allowNewMessagesFromUnfilteredChannels) {
-        return;
-      }
-
       setChannels((channels) =>
         moveChannelUpwards({
           channels,

src/components/ChannelListItem/hooks/__tests__/useIsChannelMuted.test.tsx

@@ -0,0 +1,78 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+import { fromPartial } from '@total-typescript/shoehorn';
+
+import { ChatContext } from '../../../../context/ChatContext';
+import type { ChatContextValue } from '../../../../context/ChatContext';
+import {
+  generateChannel,
+  generateUser,
+  getOrCreateChannelApi,
+  getTestClientWithUser,
+  useMockedApis,
+} from '../../../../mock-builders';
+import { useIsChannelMuted } from '../useIsChannelMuted';
+
+const clientUser = generateUser({ id: 'current-user' });
+
+const createWrapper = (client) =>
+  function Wrapper({ children }) {
+    return (
+      <ChatContext.Provider value={fromPartial<ChatContextValue>({ client })}>
+        {children}
+      </ChatContext.Provider>
+    );
+  };
+
+describe('useIsChannelMuted', () => {
+  it('does not throw when the channel has not been initialized (watched) yet', async () => {
+    const client = await getTestClientWithUser(clientUser);
+    // A channel that was never watched/queried is not initialized; calling
+    // channel.muteStatus() on it throws `_checkInitialized` and crashes the app
+    // when such a channel is rendered in the ChannelList (issue #2474).
+    const channel = client.channel('messaging', 'never-watched-channel');
+
+    expect(channel.initialized).toBe(false);
+
+    const { result } = renderHook(() => useIsChannelMuted(channel), {
+      wrapper: createWrapper(client),
+    });
+
+    expect(result.current.muted).toBe(false);
+  });
+
+  it('returns the channel mute status for an initialized channel', async () => {
+    const client = await getTestClientWithUser(clientUser);
+    const mockedChannel = generateChannel();
+    useMockedApis(client, [getOrCreateChannelApi(mockedChannel)]);
+    const channel = client.channel('messaging', mockedChannel.channel.id);
+    await channel.watch();
+
+    const { result } = renderHook(() => useIsChannelMuted(channel), {
+      wrapper: createWrapper(client),
+    });
+
+    expect(result.current.muted).toBe(false);
+  });
+
+  it('does not throw when an initialized channel has been disconnected', async () => {
+    const client = await getTestClientWithUser(clientUser);
+    const mockedChannel = generateChannel();
+    useMockedApis(client, [getOrCreateChannelApi(mockedChannel)]);
+    const channel = client.channel('messaging', mockedChannel.channel.id);
+    await channel.watch();
+
+    expect(channel.initialized).toBe(true);
+    // Once the client is disconnected (e.g. client.disconnectUser()), the channel
+    // stays initialized but channel.muteStatus() -> channel.getClient() throws
+    // "You can't use a channel after client.disconnect() was called", crashing the
+    // ChannelListItem render unless we guard against it (#2393 failure class).
+    channel.disconnected = true;
+
+    const { result } = renderHook(() => useIsChannelMuted(channel), {
+      wrapper: createWrapper(client),
+    });
+
+    expect(result.current.muted).toBe(false);
+  });
+});

src/components/ChannelListItem/hooks/useIsChannelMuted.ts

@@ -4,18 +4,33 @@ import { useChatContext } from '../../../context/ChatContext';
 
 import type { Channel } from 'stream-chat';
 
+/**
+ * `channel.muteStatus()` throws in two cases:
+ * - the channel has not been initialized yet (i.e. `.watch()`/`.query()` has not
+ *   resolved) - the ChannelList can briefly hold such channels, e.g. a
+ *   `message.new` for a channel that has not been watched yet (#2474);
+ * - the channel is disconnected (e.g. after `client.disconnectUser()`), in which
+ *   case `channel.getClient()` throws even though the channel stays initialized
+ *   (#2393 failure class).
+ * Guard against both to avoid crashing the whole app.
+ */
+const getMuteStatus = (channel: Channel) =>
+  channel.initialized && !channel.disconnected
+    ? channel.muteStatus()
+    : { createdAt: null, expiresAt: null, muted: false };
+
 export const useIsChannelMuted = (channel: Channel) => {
   const { client } = useChatContext('useIsChannelMuted');
 
-  const [muted, setMuted] = useState(channel.muteStatus());
+  const [muted, setMuted] = useState(() => getMuteStatus(channel));
 
   useEffect(() => {
-    const handleEvent = () => setMuted(channel.muteStatus());
+    const handleEvent = () => {
+      setMuted(getMuteStatus(channel));
+    };
 
-    client.on('notification.channel_mutes_updated', handleEvent);
-    return () => client.off('notification.channel_mutes_updated', handleEvent);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [muted]);
+    return client.on('notification.channel_mutes_updated', handleEvent).unsubscribe;
+  }, [channel, client]);
 
   return muted;
 };