Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

The browser says io is not defined, or socket.io.js is not found

ErrorUncaught ReferenceError: io is not defined

Short answer

io is not defined means the Socket.IO client script never loaded. By default the Socket.IO server serves it at /socket.io/socket.io.js, so a 404 there means the page is not talking to that server, or serveClient is off. Load the script from the right origin, a CDN, or install socket.io-client.

  • Applies to Socket.IO 4, Node.js 22, Express 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request the client file from the Socket.IO server itself. If this fails, the browser will fail too.

    curl -I http://localhost:3000/socket.io/socket.io.js
  2. 2Match what you see, then jump to its fix

    1. 1The 404 for socket.io.js appears on the origin that serves your HTML (a static server, a dev server, another port)The page comes from a different server than Socket.IOFix
    2. 2The server is on the same origin but the request returns 404The server does not serve the client fileFix
    3. 3The file loads with 200, but the error appears at the line that calls io()The script is loaded after the code that uses ioFix

What does the error look like?

  • Uncaught ReferenceError: io is not defined
  • GET http://localhost:3000/socket.io/socket.io.js 404 (Not Found)
  • Failed to load resource: socket.io.js

Cause 1 of 3

The page comes from a different server than Socket.IO

1Check

The relative URL /socket.io/socket.io.js is resolved against the page's own origin, so it only works when the page and the Socket.IO server share one.

curl -I http://localhost:3000/socket.io/socket.io.js; curl -I http://localhost:5173/socket.io/socket.io.js

2Fix

Load the bundle from a CDN, which the docs list with a versioned URL, or install socket.io-client and import it. Then point io at the server's URL.

npm install socket.io-client

// client code
import { io } from "socket.io-client";
const socket = io("http://localhost:3000");

3Verify

Reload; no ReferenceError and the connection appears in the server log.

curl -s "http://localhost:3000/socket.io/?EIO=4&transport=polling"

Confirmed by socket.io

Did this fix it?

Cause 2 of 3

The server does not serve the client file

1Check

Serving can be switched off with serveClient: false.

grep -rn "serveClient" src/ server.js 2>/dev/null

2Fix

Remove the option, or use the CDN or npm route above.

const io = new Server(httpServer);
// not: new Server(httpServer, { serveClient: false })

3Verify

The curl from the first step returns 200.

curl -I http://localhost:3000/socket.io/socket.io.js

Confirmed by socket.io

Did this fix it?

Cause 3 of 3

The script is loaded after the code that uses io

1Check

The file registers io as a global when it runs. Code placed above the script tag runs first.

grep -n "socket.io.js\|io(" public/index.html

2Fix

Put the script tag first, then your code.

<script src="/socket.io/socket.io.js"></script>
<script>
  const socket = io();
</script>

3Verify

Reload the page and check the console for errors.

curl -s http://localhost:3000/ | grep -n "socket.io.js\|io()"

Confirmed by socket.io

Did this fix it?

How do I stop it coming back?

  • Use socket.io-client with a bundler for any app that has a build step.
  • Keep server and client on the same major version of Socket.IO.
  • Test the curl line in the first step after every deploy that touches the proxy.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.