Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ import { Server } from 'socket.io';
✗ const Server = require('socket.io');
While CommonJS is supported, modern Node.js and TypeScript projects typically use ESM.
This code sets up a basic Socket.IO server on port 3000 that listens for client connections. When a client connects, it logs the ID, sends a 'hello' event, listens for 'message' events from that client, and broadcasts them to all connected clients. It also handles client disconnections.
import { Server } from 'socket.io';
import { createServer } from 'http';
const httpServer = createServer();
const io = new Server(httpServer, {
cors: {
origin: '*', // Allow all origins for simplicity in quickstart
methods: ['GET', 'POST']
}
});
io.on('connection', (socket) => {
console.log(`User connected: ${socket.id}`);
socket.emit('hello', `Welcome, ${socket.id}!`);
socket.on('message', (payload: string) => {
console.log(`Received message from ${socket.id}: ${payload}`);
// Broadcast the message to all connected clients
io.emit('broadcast', `Message from ${socket.id}: ${payload}`);
});
socket.on('disconnect', () => {
console.log(`User disconnected: ${socket.id}`);
});
});
const PORT = process.env.PORT ?? 3000;
httpServer.listen(PORT, () => {
console.log(`Socket.IO server listening on port ${PORT}`);
});
Debug
Known issues
breakingA critical security vulnerability (CVE-2026-33151) exists in the `socket.io-parser` dependency, allowing potential resource exhaustion via excessively large binary attachments.fixUpgrade `socket.io` to version 4.8.3 or later to ensure `socket.io-parser` (>=4.2.6) is updated.
affects: <4.8.3 for socket.io (which pulls vulnerable parser versions)
gotchaWhen deploying Socket.IO across multiple Node.js instances behind a load balancer, 'sticky sessions' are required to ensure a client's requests are always routed to the same server instance.fixConfigure your load balancer (e.g., Nginx, HAProxy) to use IP-based sticky sessions or a similar mechanism.
affects: All versions
deprecatedOlder Socket.IO versions (or their dependencies) may use Node.js's deprecated `url.parse()` function, leading to deprecation warnings in newer Node.js environments.fixUpgrade to `socket.io@4.8.2` or later, which replaces `url.parse()` with `new URL()`.
affects: <4.8.2
gotchaCalling `io.close()` on an already stopped server instance could throw an error, potentially leading to unhandled exceptions.fixUpgrade to `socket.io@4.8.3` or later, which includes a fix for this behavior.
affects: <4.8.3
Errors
Common errors & fixes
Error: Server must be passed to the constructor
The `Server` constructor was called without an `http.Server` instance or a port number.
fixInitialize the Socket.IO server with `new Server(httpServer)` or `new Server(3000)`.
DeprecationWarning: The URL.parse() method is deprecated and will be removed in a future version. Please use the WHATWG URL API.
An older version of `socket.io` or its dependencies is using the deprecated `url.parse()` function in Node.js.
fixUpgrade `socket.io` to version 4.8.2 or later.
Error: connect ECONNREFUSED ::1:3000 (or similar IP/port)
The client attempted to connect to a Socket.IO server that is not running or is listening on a different host/port.
fixEnsure the Socket.IO server is running and listening on the expected host and port. Verify the client's connection URL matches the server's address.
TypeError: socket.on is not a function
Attempting to register a client-specific event listener on the `io` (Server) instance instead of an individual `socket` instance.
fixAttach client-specific event listeners within the `io.on('connection', (socket) => { ... })` callback, using the `socket` object: `socket.on('eventName', handler)`. WebSocket connection to 'ws://localhost:3000/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400
This often indicates a Cross-Origin Resource Sharing (CORS) issue or an incorrect Engine.IO path configuration between the client and server.
fixEnsure CORS options are correctly configured on the server-side, e.g., `new Server(httpServer, { cors: { origin: "*", methods: ["GET", "POST"] } })`. Audit
Dependencies
No dependency data recorded yet.