socketio/socket.io · error · Error

You are trying to attach socket.io to an express request han

Error message

You are trying to attach socket.io to an express request handler function. Please pass a http.Server instance.

What it means

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.

Source

Thrown at packages/socket.io/lib/index.ts:493

    return this.attach(srv, opts);
  }

  /**
   * Attaches socket.io to a server or port.
   *
   * @param srv - server or port
   * @param opts - options passed to engine.io
   * @return self
   */
  public attach(
    srv: TServerInstance | number,
    opts: Partial<ServerOptions> = {},
  ): this {
    if ("function" == typeof srv) {
      const msg =
        "You are trying to attach socket.io to an express " +
        "request handler function. Please pass a http.Server instance.";
      throw new Error(msg);
    }

    // handle a port as a string
    if (Number(srv) == srv) {
      srv = Number(srv);
    }

    if ("number" == typeof srv) {
      debug("creating http server and binding to %d", srv);
      const port = srv;
      srv = createServer((_req, res) => {
        res.writeHead(404);
        res.end();
      });
      srv.listen(port);
    }

    // merge the options passed to the Socket.IO server

View on GitHub (pinned to ae7fb46e08)

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.

Example fix

// before
const app = express();
const io = new Server(app); // throws: app is a function
app.listen(3000);

// after
const app = express();
const httpServer = http.createServer(app);
const io = new Server(httpServer);
httpServer.listen(3000);

Defensive patterns

Strategy: type-guard

Validate before calling

const http = require('http');
function isServer(srv){ return srv && typeof srv==='object' && typeof srv.listen==='function' && typeof srv!=='function'; }

Type guard

function isHttpServer(srv){ return !!srv && typeof srv==='object' && typeof srv.listen==='function' && typeof srv.emit==='function'; }

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

AI-assisted analysis of socketio/socket.io@ae7fb46e08 (2026-08-03). Data as JSON: /data/errors/c4b781bcdb70194c.json. Report an issue: GitHub.