Troubleshooting "initial WS connection could not be established" error

Sometimes there are reports of a client-side error that looks like this:

 {"code":"","StatusCode":"","message":"initial WS connection could not be established","isWSFailure":true}

These errors come from the client itself, and can be difficult to debug on the Stream side, since the request never actually reaches the Stream servers. 

Luckily, this error has three common causes that are useful in troubleshooting:

1. Slow Connection
   If a user is connecting with a slow internet connection, the time it takes to connect to the Websocket can exceed the default value of 3000ms. It may be hard to know for sure if this is error is the result of slow connections, especially if your users are dispersed across many different areas. You can try increasing the timeout in your connect call. 
   

   const chatClient = StreamChat.getInstance(API_KEY, {
       timeout: 6000
   });

2. Race Condition
   If a request is made to the API before the Websocket connection is actually established, it will throw this error. For any initial calls being made when Chat is opened (queryChannels could be a common one) you can add a conditional statement to make sure the client has connected before anything else. The SDKs will handle this on their own, but in a custom built UI, it's a good practice to have this in place. 

   if (!client) return <p>Waiting for connection to be established with user: {userId}...</p>;
   
   return (
     <Chat client={client}
       {children}
     </Chat>
   )

3. Firewall/Blocked Domain
   It's not uncommon that the device or network a user is connecting on has a firewall that is blocking the Stream domain URL or IP address. This is more common for corporate networks or devices. Try whitelisting the following URL:

   https://chat.stream-io-api.com