https://socket.io/assets/js/efbff91e.e46f00a1.js

1"use strict";(self.webpackChunksample_website=self.webpackChunksample_website||[]).push([[3212],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>k});var o=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function a(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?i(Object(n),!0).forEach((function(t){r(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):i(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function l(e,t){if(null==e)return{};var n,o,r=function(e,t){if(null==e)return{};var n,o,r={},i=Object.keys(e);for(o=0;o<i.length;o++)n=i[o],t.indexOf(n)>=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(o=0;o<i.length;o++)n=i[o],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=o.createContext({}),c=function(e){var t=o.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},p=function(e){var t=c(e.components);return o.createElement(s.Provider,{value:t},e.children)},u="mdxType",d={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},m=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,s=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=c(n),m=r,k=u["".concat(s,".").concat(m)]||u[m]||d[m]||i;return n?o.createElement(k,a(a({ref:t},p),{},{components:n})):o.createElement(k,a({ref:t},p))}));function k(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,a=new Array(i);a[0]=m;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l[u]="string"==typeof e?e:r,a[1]=l;for(var c=2;c<i;c++)a[c]=n[c];return o.createElement.apply(null,a)}return o.createElement.apply(null,n)}m.displayName="MDXCreateElement"},2698:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>a,default:()=>d,frontMatter:()=>i,metadata:()=>l,toc:()=>c});var o=n(3117),r=(n(7294),n(3905));const i={title:"Troubleshooting connection issues",sidebar_label:"Troubleshooting",sidebar_position:5,slug:"/troubleshooting-connection-issues/"},a=void 0,l={unversionedId:"categories/Documentation/troubleshooting",id:"version-3.x/categories/Documentation/troubleshooting",title:"Troubleshooting connection issues",description:"First and foremost, please note that disconnections are common and expected, even on a stable Internet connection:",source:"@site/versioned_docs/version-3.x/categories/01-Documentation/troubleshooting.md",sourceDirName:"categories/01-Documentation",slug:"/troubleshooting-connection-issues/",permalink:"/docs/v3/troubleshooting-connection-issues/",draft:!1,editUrl:"https://github.com/socketio/socket.io-website/edit/main/versioned_docs/version-3.x/categories/01-Documentation/troubleshooting.md",tags:[],version:"3.x",lastUpdatedAt:1784117104,formattedLastUpdatedAt:"Jul 15, 2026",sidebarPosition:5,frontMatter:{title:"Troubleshooting connection issues",sidebar_label:"Troubleshooting",sidebar_position:5,slug:"/troubleshooting-connection-issues/"},sidebar:"version-3.x/sidebar",previous:{title:"Testing",permalink:"/docs/v3/testing/"},next:{title:"Initialization",permalink:"/docs/v3/server-initialization/"}},s={},c=[{value:"In Node.js",id:"in-nodejs",level:2},{value:"Listening to the <code>connect_error</code> event",id:"listening-to-the-connect_error-event",level:3},{value:"Debug logs",id:"debug-logs",level:3},{value:"In the browser",id:"in-the-browser",level:2},{value:"In the Network Monitor of your browser",id:"in-the-network-monitor-of-your-browser",level:3}],p={toc:c},u="wrapper";function d(e){let{components:t,...i}=e;return(0,r.kt)(u,(0,o.Z)({},p,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"First and foremost, please note that disconnections are common and expected, even on a stable Internet connection:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"anything between the user and the Socket.IO server may encounter a temporary failure or be restarted"),(0,r.kt)("li",{parentName:"ul"},"the server itself may be killed as part of an autoscaling policy"),(0,r.kt)("li",{parentName:"ul"},"the user may lose connection or switch from WiFi to 4G, in case of a mobile browser"),(0,r.kt)("li",{parentName:"ul"},"the browser itself may freeze an inactive tab"),(0,r.kt)("li",{parentName:"ul"},"...")),(0,r.kt)("p",null,"That being said, the Socket.IO client will always try to reconnect, unless specifically told otherwise."),(0,r.kt)("p",null,"Let's review how y

1ou can troubleshoot a connection failure."),(0,r.kt)("h2",{id:"in-nodejs"},"In Node.js"),(0,r.kt)("h3",{id:"listening-to-the-connect_error-event"},"Listening to the ",(0,r.kt)("inlineCode",{parentName:"h3"},"connect_error")," event"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js"},'const socket = require("socket.io-client")("https://example.com");\n\nsocket.on("connect_error", (err) => {\n  console.log(`connect_error due to ${err.message}`);\n});\n')),(0,r.kt)("p",null,"Common errors:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"the server might not be reachable")),(0,r.kt)("p",null,"Please make sure the Socket.IO server is actually reachable at the given URL. You can test it with:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'curl "https://example.com/socket.io/?EIO=4&transport=polling"\n')),(0,r.kt)("p",null,"which should return something like this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'0{"sid":"Lbo5JLzTotvW3g2LAAAA","upgrades":["websocket"],"pingInterval":25000,"pingTimeout":5000}\n')),(0,r.kt)("p",null,"If that's not the case, please check that the Socket.IO server is running, and that there is nothing in between that prevents the connection."),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"there might be an issue with the SSL certificate of the server")),(0,r.kt)("p",null,"You can test it with ",(0,r.kt)("inlineCode",{parentName:"p"},"rejectUnauthorized")," set to ",(0,r.kt)("inlineCode",{parentName:"p"},"false"),"."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js"},'const socket = require("socket.io-client")("https://example.com", {\n  rejectUnauthorized: false // WARN: please do not do this in production\n});\n')),(0,r.kt)("p",null,"If that works, it could mean that the SSL certificate is invalid, or, if you are using a self-signed certificate, that you have to trust it on the client-side:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js"},'const socket = require("socket.io-client")("https://example.com", {\n  ca: fs.readFileSync(\'./cert.pem\')\n});\n')),(0,r.kt)("h3",{id:"debug-logs"},"Debug logs"),(0,r.kt)("p",null,"As explained ",(0,r.kt)("a",{parentName:"p",href:"/docs/v3/logging-and-debugging/"},"here"),", you can also enable the logs to see what's going on under the hood."),(0,r.kt)("p",null,"For reference, here are the logs for a successful connection:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'$ DEBUG=socket* node index.js\n\nsocket.io-client:url parse https://example.com +0ms\nsocket.io-client new io instance for https://example.com +0ms\nsocket.io-client:manager readyState closed +0ms\nsocket.io-client:manager opening https://example.com +0ms\nsocket.io-client:manager connect attempt will timeout after 20000 +7ms\nsocket.io-client:manager readyState opening +1ms\nsocket.io-client:manager open +6ms\nsocket.io-client:manager cleanup +0ms\nsocket.io-client:socket transport is open - connecting +0ms\nsocket.io-client:manager writing packet {"type":0,"nsp":"/"} +1ms\nsocket.io-parser encoding packet {"type":0,"nsp":"/"} +0ms\nsocket.io-parser encoded {"type":0,"nsp":"/"} as 0 +0ms\nsocket.io-parser decoded 0{"sid":"emVyzJPFYLlVMB7YAAAD"} as {"type":0,"nsp":"/","data":{"sid":"emVyzJPFYLlVMB7YAAAD"}} +2ms\nsocket.io-client:socket socket connected with id emVyzJPFYLlVMB7YAAAD +2ms\n')),(0,r.kt)("h2",{id:"in-the-browser"},"In the browser"),(0,r.kt)("h3",{id:"in-the-network-monitor-of-your-browser"},"In the Network Monitor of your browser"),(0,r.kt)("p",null,"In most cases, you should see something like this:"),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Network monitor upon success",src:n(5290).Z,width:"585",height:"216"})),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},"the Engine.IO handshake (contains the session ID \u2014 here, ",(0,r.kt)("inlineCode",{parentName:"li"},"zBjrh...AAAK")," \u2014 that is used in subsequent requests)"),(0,r.kt)("li",{parentName:"ol"},"the Socket.IO handshake request (contains the value of the ",(0,r.kt)("inlineCode",{parentName:"li"},"auth")," option)"),(0,r.kt)("li",{parentName:"ol"}

1,"the Socket.IO handshake response (contains the ",(0,r.kt)("a",{parentName:"li",href:"/docs/v3/server-socket-instance/#Socket-id"},"Socket#id"),")"),(0,r.kt)("li",{parentName:"ol"},"the WebSocket connection"),(0,r.kt)("li",{parentName:"ol"},"the first HTTP long-polling request, which is closed once the WebSocket connection is established")),(0,r.kt)("p",null,"The Socket.IO server may return the following HTTP status:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101"},(0,r.kt)("inlineCode",{parentName:"a"},"101 Switching Protocols")),": when the WebSocket connection is established"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200"},(0,r.kt)("inlineCode",{parentName:"a"},"200 OK")),": when in HTTP long-polling mode (",(0,r.kt)("inlineCode",{parentName:"li"},"GET")," for reading, ",(0,r.kt)("inlineCode",{parentName:"li"},"POST")," for writing)"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400"},(0,r.kt)("inlineCode",{parentName:"a"},"400 Bad Request")),": when something went wrong")),(0,r.kt)("p",null,"In case of an HTTP 400 response, the response payload will be one of the following:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'{"code":0,"message":"Transport unknown"}'))),(0,r.kt)("p",null,"The ",(0,r.kt)("inlineCode",{parentName:"p"},"transport")," query parameter is missing or invalid."),(0,r.kt)("p",null,"To reproduce: ",(0,r.kt)("inlineCode",{parentName:"p"},'curl "<url>/socket.io/"')," or ",(0,r.kt)("inlineCode",{parentName:"p"},'curl "<url>/socket.io/?transport=udp"')),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'{"code":1,"message":"Session ID unknown"}'))),(0,r.kt)("p",null,"The session ID (included in the ",(0,r.kt)("inlineCode",{parentName:"p"},"sid")," query parameter) is unknown from the server. That may happen in a ",(0,r.kt)("a",{parentName:"p",href:"/docs/v3/using-multiple-nodes/"},"multi-server setup"),"."),(0,r.kt)("p",null,"To reproduce: ",(0,r.kt)("inlineCode",{parentName:"p"},'curl "<url>/socket.io/?transport=polling&sid=1234"')),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'{"code":2,"message":"Bad handshake method"}'))),(0,r.kt)("p",null,"The initial request must be a ",(0,r.kt)("inlineCode",{parentName:"p"},"GET")," request."),(0,r.kt)("p",null,"To reproduce: ",(0,r.kt)("inlineCode",{parentName:"p"},'curl -X PUT "<url>/socket.io/?transport=polling"')),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'{"code":3,"message":"Bad request"}'))),(0,r.kt)("p",null,"An error has occurred during the handshake process."),(0,r.kt)("p",null,"This error cannot be easily reproduced with a single ",(0,r.kt)("inlineCode",{parentName:"p"},"curl")," command."),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'{"code":4,"message":"Forbidden"}'))),(0,r.kt)("p",null,"The request was denied in the ",(0,r.kt)("a",{parentName:"p",href:"/docs/v3/server-initialization/#allowRequest"},(0,r.kt)("inlineCode",{parentName:"a"},"allowRequest"))," handler."),(0,r.kt)("p",null,"To reproduce:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js"},'const io = require("socket.io")(httpServer, {\n  allowRequest: (req, callback) => {\n    callback(null, false);\n  }\n});\n')),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'{"code":5,"message":"Unsupported protocol version"}'))),(0,r.kt)("p",null,"The protocol version is not supported by the server. Support for Socket.IO v2 clients must be explicitly enabled with the ",(0,r.kt)("a",{parentName:"p",href:"/docs/v3/server-initialization/#allowEIO3"},(0,r.kt)("inlineCode",{parentName:"a"},"allowEIO3"))," option:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-js"},'const io = require("socket.io")(httpServer, {\n  allowEIO3: true // false by default\n});\n')),(0,r.kt)("p",null,"To reproduce: ",(0,r.kt)("inlineCode",{parentName:"p"},'curl "<url>/socket.io/?transport=polling&EIO=3"')),(0,r.kt)("p",null,"Another quite common error is:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at ...\n")),(0,r.kt)("p",null,"Which probably means that you have to enable ",(0,r.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"},"Cross-Origin Resource Sharing")," (CORS) on the server-side. Please see the documentation ",(0,r.kt)("a",{parentName:"p",href:"/docs/v3/h

1andling-cors/"},"here"),"."))}d.isMDXComponent=!0},5290:(e,t,n)=>{n.d(t,{Z:()=>o});const o=n.p+"assets/images/network-monitor-2e47dbe233100aa290595f8687a9fcba.png"}}]);