Mark Pigge created TINKERPOP-3160:
-------------------------------------
Summary: Node.js 22+: Gremlin Fails with network error and HTTP
101 Status Due to WebSocket Limitation in undici
Key: TINKERPOP-3160
URL: https://issues.apache.org/jira/browse/TINKERPOP-3160
Project: TinkerPop
Issue Type: Bug
Components: javascript
Affects Versions: 3.7.3
Reporter: Mark Pigge
*📌 Overview:*
After upgrading to {*}Node.js 22 or newer{*}, applications using the *Gremlin
driver* encounter {{network error}} failures when trying to connect to graph
database AWS Neptune. These failures are caused by the removal of built-in
WebSocket support in Node.js and reliance on {{{}undici{}}}, which does *not
support custom headers* or handle the WebSocket handshake properly in this
context.
----
*❌ Symptoms:*
* {{Gremlin}} client fails to connect
* Network error during connection
* HTTP 101 Switching Protocols error with no upgrade
* Headers like {{Authorization}} or {{Host}} are missing or ignored
* Stack trace shows underlying issues in WebSocket handshake
----
*🎯 Root Cause:*
* Node.js 22+ no longer includes a global {{WebSocket}} implementation
* The fallback (via {{{}undici{}}}) *does not support* custom headers
* This breaks clients that rely on authenticated WebSocket connections (like
Gremlin)
* Result: WebSocket upgrade fails with a 101 status and unresolved {{network
error}}
----
*✅ Workaround:*
You can override the default WebSocket globally with the {{ws}} library, which
supports custom headers and proper handshake behavior.
import \{ WebSocket as WS } from 'ws';
(globalThis as any).WebSocket = WS;
This should be done *early in your application startup* before any Gremlin
connections are created.
----
*📄 Example Fix for Gremlin Driver:*
import \{ WebSocket as WS } from 'ws';
(globalThis as any).WebSocket = WS;
import \{ DriverRemoteConnection } from 'gremlin';
const connection = new DriverRemoteConnection(
'wss://your-gremlin-endpoint:8182/gremlin', \{
// headers like Authorization must now be passed via a custom WebSocket
}
);
----
*📚 References:*
* Node.js change: [{{undici}} removed WebSocket
support|https://github.com/nodejs/undici/discussions/3836]
* Community write-up: [Resolving Gremlin network errors after upgrading to
Node.js
23|https://medium.com/@python-javascript-php-html-css/resolving-gremlin-network-errors-after-upgrading-to-node-js-23-3591c0e45caa]
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
