gatsbyjs/gatsby · error

[socket.io] Disconnected from dev server.

Error message

[socket.io] Disconnected from dev server.

What it means

Development-runtime notice from Gatsby's socket.io client wrapper: the socket emitted a disconnect event (dev server stopped, restarted, or network drop). Shown to explain why hot updates stopped; the socket.io client auto-reconnects, and the message throttles XHR ERR_CONNECTION_REFUSED spam in the console.

Source

Thrown at packages/gatsby/cache-dir/socketIo.js:34

        socket.on(`reconnect_attempt`, () => {
          socket.io.opts.transports = [`polling`, `websocket`]
        })

        socket.on(`message`, msg => {
          if (msg.type === `overlayError`) {
            if (msg.payload.message) {
              reportError(msg.payload.id, msg.payload.message)
            } else {
              clearError(msg.payload.id)
            }
            ___emitter.emit(msg.type, msg.payload)
          }
        })

        // Prevents certain browsers spamming XHR 'ERR_CONNECTION_REFUSED'
        // errors within the console, such as when exiting the develop process.
        socket.on(`disconnect`, () => {
          console.warn(`[socket.io] Disconnected from dev server.`)
        })
      } catch (err) {
        console.error(`Could not connect to socket.io on dev server.`)
      }
    }
    return socket
  } else {
    return null
  }
}

// Tell websocket-manager.js the new path we're on.
// This will help the backend prioritize queries for this
// path.
function registerPath(path) {
  socket.emit(`registerPath`, path)
}

View on GitHub (pinned to e85d62f177)

Solutions

1. Expected when `gatsby develop` exits or restarts — reload the page once the server is back
2. If it persists while the server runs, check the websocket isn't blocked (proxy, firewall, HMR customizations)
3. Restart the dev server if the client fails to reconnect automatically

When it happens

Trigger: Thrown at packages/gatsby/cache-dir/socketIo.js:34 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/09305f4abb008322. Report an issue: GitHub.