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)