mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Can only make Socks5 connections to TCP hosts

Error message

Can only make Socks5 connections to TCP hosts

What it means

Thrown as a MongoInvalidArgumentError in makeSocks5Connection() after parseConnectOptions(options) returns a destination that lacks a string host or numeric port. Socks5 proxying requires a TCP destination (host:port); Unix-domain-socket destinations (socketPath) cannot be tunneled through Socks5. This fires only when proxyHost is set.

Solutions

1. Do not combine proxyHost with a Unix-socket (socketPath) destination — Socks5 only supports TCP targets
2. If you need to proxy, connect to the MongoDB instance via a TCP host:port instead of a socket path
3. Remove the proxyHost option when connecting over a local Unix socket

Example fix

// before: proxy + unix socket is invalid
new MongoClient('mongodb://%2Ftmp%2Fmongo.sock/?proxyHost=proxy.local&proxyPort=1080');

// after: proxy requires a TCP destination
new MongoClient('mongodb://mongo.internal:27017/?proxyHost=proxy.local&proxyPort=1080');

const hasProxy = !!options.proxyHost;
const isSocket = typeof options.hostAddress?.socketPath === 'string';
if (hasProxy && isSocket) {
  throw new Error('Socks5 proxy cannot target a Unix socket; use a TCP host:port destination');
}

function proxyTargetIsTcp(opts: { proxyHost?: string; hostAddress?: { host?: string; port?: number; socketPath?: string } }): boolean {
  return typeof opts.hostAddress?.host === 'string' && typeof opts.hostAddress?.port === 'number';
}

When it happens

Trigger: Configuring proxyHost (Socks5 proxy) while the destination is a Unix socket (options.hostAddress.socketPath is set) rather than a TCP host. The driver connects to the proxy, then tries to parse the destination and finds no TCP host/port.

Common situations: Mixing a Socks5 proxy with a Unix-domain-socket MongoDB deployment (e.g. sidecar on the same host); misconfiguration where socketPath is set globally and proxyHost is also set.

Related errors

• ${MongoError.buildErrorMessage(cause)}
• Can only specify both of proxy username/password or neither
• Cannot set both proxyOptions and kmsConnectCallback
• Cannot set both proxyOptions and kmsConnectCallback
• Must specify proxyHost if other proxy options are passed

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/33cf5bc65d89042a. Report an issue: GitHub.

Appendix: source

Thrown at src/cmap/connect.ts:504

}

async function makeSocks5Connection(options: MakeConnectionOptions): Promise<Stream> {
  const hostAddress = HostAddress.fromHostPort(
    options.proxyHost ?? '', // proxyHost is guaranteed to set here
    options.proxyPort ?? 1080
  );

  // First, connect to the proxy server itself:
  const rawSocket = await makeSocket({
    ...options,
    hostAddress,
    tls: false,
    proxyHost: undefined
  });

  const destination = parseConnectOptions(options) as net.TcpNetConnectOpts;
  if (typeof destination.host !== 'string' || typeof destination.port !== 'number') {
    throw new MongoInvalidArgumentError('Can only make Socks5 connections to TCP hosts');
  }

  socks ??= loadSocks();

  let existingSocket: Stream;

  try {
    // Then, establish the Socks5 proxy connection:
    const connection = await socks.SocksClient.createConnection({
      existing_socket: rawSocket,
      timeout: options.connectTimeoutMS,
      command: 'connect',
      destination: {
        host: destination.host,
        port: destination.port
      },
      proxy: {
        // host and port are ignored because we pass existing_socket

View on GitHub (pinned to dce7939f86)