Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createProxyServer
✓ import { createProxyServer } from 'http-proxy-3';
✗ const httpProxy = require('http-proxy-3'); const proxy = httpProxy.createProxyServer();
http-proxy-3 is primarily designed for ES Modules, though CommonJS `require` might work with transpilation or specific Node.js loader configurations. `createProxyServer` is the main factory function.
ProxyServerOptions
✓ import type { ProxyServerOptions } from 'http-proxy-3';
This type definition is crucial for TypeScript users to correctly configure the proxy server instance.
ProxyServer
✓ import type { ProxyServer } from 'http-proxy-3';
Represents the instance returned by `createProxyServer`, useful for type annotations when working with proxy event listeners or methods like `web()` and `ws()`.
This quickstart sets up a basic HTTP and WebSocket proxy that forwards requests from port 8000 to a target server running on port 9000, demonstrating core proxying functionality and error handling.
import * as http from 'node:http';
import { createProxyServer, type ProxyServerOptions } from 'http-proxy-3';
// Create a target HTTP server
const targetServer = http.createServer((req, res) => {
console.log(`Target received: ${req.method} ${req.url}`);
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end('Hello from the target server!');
});
targetServer.listen(9000, () => {
console.log('Target server listening on http://localhost:9000');
});
// Create a basic HTTP proxy server
const proxyOptions: ProxyServerOptions = {
target: 'http://localhost:9000',
ws: true // Enable websocket proxying
};
const proxy = createProxyServer(proxyOptions);
// Handle proxy errors
proxy.on('error', (err, req, res) => {
console.error('Proxy Error:', err);
if (res && res.writeHead) {
res.writeHead(500, { 'Content-Type': 'text/plain' });
res.end('Something went wrong with the proxy.');
}
});
// Create a proxy listening server
const proxyServer = http.createServer((req, res) => {
console.log(`Proxying request: ${req.method} ${req.url}`);
proxy.web(req, res);
});
proxyServer.on('upgrade', (req, socket, head) => {
console.log(`Proxying websocket upgrade: ${req.url}`);
proxy.ws(req, socket, head);
});
proxyServer.listen(8000, () => {
console.log('Proxy server listening on http://localhost:8000');
console.log('Test with: curl http://localhost:8000');
console.log('Test websockets with a client connecting to ws://localhost:8000');
});
Debug
Known issues
breakinghttp-proxy-3 requires Node.js version 18 or higher. Applications running on older Node.js runtimes must upgrade their environment before adopting this package.fixUpgrade Node.js to version 18 or newer.
affects: <1.23.0
breakingThis library is a complete rewrite of `http-proxy`, addressing many longstanding issues including socket leaks and uncatchable WebSocket errors in the original package. While API compatible, direct migration from `http-proxy` may expose subtle behavioral changes or require updating code that relied on deprecated/insecure APIs (e.g., `URL` instead of `parse`).fixThoroughly test existing proxy configurations after upgrading from `http-proxy`. Review and update any custom request/response handling logic that might rely on older Node.js or `http-proxy` internals.
affects: >=1.0.0
gotchaThe README notes that using the proxy server introduces a performance penalty, with proxied operations potentially taking 'about twice as long' compared to direct connections. This should be considered for highly performance-sensitive applications.fixBenchmark your application's specific use case to determine the impact. Optimize backend services or consider alternative architectures if the performance overhead is unacceptable.
affects: >=1.0.0
gotchaHTTP/2 support in http-proxy-3 is achieved via the `fetch` API and is currently marked as 'experimental'. While functional and tested, the API and behavior may change in future versions.fixUse HTTP/2 features with caution in production environments. Monitor release notes for changes related to HTTP/2 support and be prepared to adapt configurations as the feature matures.
affects: >=1.0.0
breakinghttp-proxy-3 fixes a significant security vulnerability (related to issue #1647 in the original http-party/node-http-proxy). Using older, unmaintained versions of `http-proxy` exposes applications to this vulnerability.fixImmediately upgrade to http-proxy-3 to benefit from this and other security patches.
affects: <1.0.0 (for http-proxy-3); all versions of unpatched http-proxy
Errors
Common errors & fixes
Error: listen EADDRINUSE: address already in use :::8000
The port the proxy server is trying to listen on is already in use by another process.
fixChange the proxy's listening port to an available one, or stop the process currently using the port (e.g., `kill -9 <PID>` on Linux/macOS or `netstat -ano | findstr :<PORT>` followed by `taskkill /PID <PID> /F` on Windows).
Error: connect ECONNREFUSED 127.0.0.1:9000
The proxy server could not connect to the target server because the target server is not running or its address/port is incorrect.
fixEnsure the target server is running and accessible at the configured `target` address and port. Verify no firewalls are blocking the connection between the proxy and target.
Proxy Error: Could not proxy request /socket.io/?EIO=3&transport=websocket to ws://localhost:9000/socket.io/?EIO=3&transport=websocket (ECONNREFUSED)
The proxy failed to establish a WebSocket connection to the target server, often because the target does not support WebSockets or the WebSocket server isn't running.
fixConfirm that the target server correctly implements and listens for WebSocket connections. Ensure `ws: true` is set in the `createProxyServer` options if you intend to proxy WebSockets.
HTTP/1.1 407 Proxy Authentication Required
The proxy itself (or an upstream proxy) requires authentication before it will forward the request.
fixProvide the necessary authentication credentials in the proxy configuration if `http-proxy-3` is acting as a client to another authenticated proxy, or ensure your client accessing `http-proxy-3` provides valid credentials if `http-proxy-3` is configured to require them.
Error: Parse Error: HPE_INVALID_HEADER_TOKEN
The target server returned a malformed HTTP header, which Node.js's HTTP parser cannot interpret.
fixInspect the responses from your target server for invalid characters or formatting in HTTP headers. This often indicates an issue with the target server's HTTP implementation.
Audit
Dependencies
No dependency data recorded yet.