You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tinkerpop.apache.org by "Mark Pigge (Jira)" <ji...@apache.org> on 2025/05/26 07:35:00 UTC
[jira] [Created] (TINKERPOP-3160) Node.js 22+: Gremlin Fails with network error and HTTP 101 Status Due to WebSocket Limitation in undici
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)