`--use-env-proxy` breaks WebSocket (ws library) long connections via http.request() interception

[evan966890]

Version

v22.22.0

Platform

Darwin 25.2.0 arm64

Subsystem

http, net

What steps will reproduce the bug?

1. Start an HTTP proxy on 127.0.0.1:10808
2. Set environment variables:

   HTTP_PROXY=http://127.0.0.1:10808
   HTTPS_PROXY=http://127.0.0.1:10808
   

3. Run a Node.js application that uses the ws library to maintain a WebSocket long connection (e.g., Discord gateway via wss://gateway.discord.gg) with NODE_USE_ENV_PROXY=true or --use-env-proxy
4. The WebSocket connection will repeatedly disconnect with close codes 1005/1006

How often does it reproduce? Is there a required condition?

100% reproducible. The WebSocket disconnects within minutes to hours (varies by proxy and server). Without --use-env-proxy, the same connection stays stable indefinitely.

What is the expected behavior? Why is that the expected behavior?

WebSocket connections via the ws library should work normally with --use-env-proxy. The proxy interception should either:

• Properly tunnel WebSocket upgrade requests through the HTTP proxy, or
• Not intercept WebSocket connections at all (since ws uses raw TCP/TLS via http.request() upgrade)

What do you see instead?

When --use-env-proxy is enabled, the proxy agent intercepts http.request() calls used by the ws library for WebSocket upgrades. This causes:

• WebSocket connections to close with code 1005 (no status code) or 1006 (abnormal closure)
• Repeated reconnection attempts that also fail
• The application effectively loses real-time connectivity

Workaround

Instead of --use-env-proxy, use --require=preload.cjs with:

const { EnvHttpProxyAgent, setGlobalDispatcher } = require('undici');
setGlobalDispatcher(new EnvHttpProxyAgent());

This only patches undici's fetch dispatcher without intercepting http.request()/https.request(), so ws library connections work normally while fetch() calls still go through the proxy.

Context

This was discovered while running an application (OpenClaw, an AI agent gateway) that uses:

• ws library for Discord WebSocket gateway (long-lived connection)
• fetch() for REST API calls and OpenAI embedding API

The --use-env-proxy flag was needed to make fetch() calls go through the proxy, but it broke the WebSocket connection. The workaround above (patching only the undici global dispatcher) solves both needs.

Related

• Tracking issue: Tracking issue: HTTP_PROXY/HTTPS_PROXY/NO_PROXY support in Node.js #57872
• The tracking issue notes that supporting proxy in http(s) builtins "might be too risky" — this is a concrete example of that risk
• PR http,https: add built-in proxy support in http/https.request and Agent #58980 (initial http/https builtin proxy support) may be the source of the interception that breaks ws

[joyeecheung]

Judging from the description it may have something to do with keep alive settings not being inherited correctly, going to take a look at what ws does..

[joyeecheung]

I think this may fix it, but I am struggling to write a regression test for it. Do you have a minimal reproduction for testing?

[joyeecheung]

I did a bit more digging to try to reproduce it, and I think the analysis might have been misled. ws supplies its own createConnection so what you are seeing is probably not from --use-env-proxy - it might be that the application (OpenClaw?) not using the built-in proxy at all and you might have some other proxy agent support plumbed into the pipeline elsewhere.

(Maybe @lpinca can help confirm?)

[lpinca]

@joyeecheung sorry I missed the ping, yes ws uses its own createConnection to skip the default agent. However, it honors the agent option if provided.

[joyeecheung]

@lpinca Thanks, so it's not very likely an issue of --use-env-proxy itself right? Since --use-env-proxy doesn't affect custom agents - the user have to opt into it via proxyEnv instead...

[lpinca]

Yes, I did not follow the development of --use-env-proxy but if does not interfere with

http.get({ createConnection: net.connect });

or

http.get({ agent: customOrDefaultGlobalAgent });

then it is very unlikely to be related.

[joyeecheung]

It does affect the default global agent's configuration, though I am not sure if that's what's happening in this issue. @evan966890 Can you clarify if in your reproduction, how you are using ws?