[
https://issues.apache.org/jira/browse/TINKERPOP-3160?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Andrea C updated TINKERPOP-3160:
--------------------------------
Attachment: neptune.js
> 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
> Priority: Critical
> Attachments: neptune.js
>
>
> *📌 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)
