{"id":"c4b781bcdb70194c","repo":"socketio/socket.io","slug":"you-are-trying-to-attach-socket-io-to-an-express-r","errorCode":null,"errorMessage":"You are trying to attach socket.io to an express request handler function. Please pass a http.Server instance.","messagePattern":"You are trying to attach socket\\.io to an express request handler function\\. Please pass a http\\.Server instance\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/socket.io/lib/index.ts","lineNumber":493,"sourceCode":"    return this.attach(srv, opts);\n  }\n\n  /**\n   * Attaches socket.io to a server or port.\n   *\n   * @param srv - server or port\n   * @param opts - options passed to engine.io\n   * @return self\n   */\n  public attach(\n    srv: TServerInstance | number,\n    opts: Partial<ServerOptions> = {},\n  ): this {\n    if (\"function\" == typeof srv) {\n      const msg =\n        \"You are trying to attach socket.io to an express \" +\n        \"request handler function. Please pass a http.Server instance.\";\n      throw new Error(msg);\n    }\n\n    // handle a port as a string\n    if (Number(srv) == srv) {\n      srv = Number(srv);\n    }\n\n    if (\"number\" == typeof srv) {\n      debug(\"creating http server and binding to %d\", srv);\n      const port = srv;\n      srv = createServer((_req, res) => {\n        res.writeHead(404);\n        res.end();\n      });\n      srv.listen(port);\n    }\n\n    // merge the options passed to the Socket.IO server","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/socketio/socket.io/blob/ae7fb46e08c5ed964b4a1ea8b1703e816511598e/packages/socket.io/lib/index.ts#L475-L511","documentation":"Thrown by Server.attach()/listen() when the srv argument is a function. The most common cause is passing app (an Express application/request-handler function) instead of an http.Server instance. Socket.IO needs the actual HTTP server to upgrade WebSockets; a request handler function cannot do that.","triggerScenarios":"Calling new Server(app) or io.attach(app) / io.listen(app) where app is an Express app; or passing any function where a Server/port is expected.","commonSituations":"Copy-pasting `const io = new Server(app)` from an Express-without-http-server snippet; upgrading to socket.io v3/v4 where attaching to the raw app is no longer supported the same way; or passing app.listen() return value incorrectly.","solutions":["Create an http.Server first and pass that: const httpServer = http.createServer(app); then new Server(httpServer).","Alternatively attach to a port: new Server(3000).","Ensure you call httpServer.listen(port) (not app.listen) so Socket.IO binds to the same server."],"exampleFix":"// before\nconst app = express();\nconst io = new Server(app); // throws: app is a function\napp.listen(3000);\n\n// after\nconst app = express();\nconst httpServer = http.createServer(app);\nconst io = new Server(httpServer);\nhttpServer.listen(3000);","handlingStrategy":"type-guard","validationCode":"const http = require('http');\nfunction isServer(srv){ return srv && typeof srv==='object' && typeof srv.listen==='function' && typeof srv!=='function'; }","typeGuard":"function isHttpServer(srv){ return !!srv && typeof srv==='object' && typeof srv.listen==='function' && typeof srv.emit==='function'; }","tryCatchPattern":null,"preventionTips":["Always pass an http.Server (http.createServer(app)) or a port number to new Server().","Never pass an Express app directly.","Call httpServer.listen(), not app.listen(), when sharing the server with Socket.IO."],"tags":["server","express","http","setup","attach"],"analyzedSha":"ae7fb46e08c5ed964b4a1ea8b1703e816511598e","analyzedAt":"2026-08-03T19:08:14.127Z","schemaVersion":2}