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 when establishing a Socks5 proxied connection if the destination parsed by parseConnectOptions is not a TCP target (i.e. host is not a string or port is not a number). Socks5 cannot tunnel to a Unix domain socket, so the driver refuses to attempt it. This is a configuration error: proxyHost was set but the target hostAddress is a socketPath.

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 3366c21a63)

Solutions

1. Do not combine proxyHost with a Unix socket path; remove proxyHost/proxyPort when connecting via socketPath.
2. If you must go through Socks5, target a TCP host:port instead of a Unix socket.
3. Re-check the URI scheme: use mongodb://host:port with proxy options, not a percent-encoded socket path.

Example fix

// before
new MongoClient('mongodb://%2Ftmp%2Fmongodb.sock', { proxyHost: 'proxy', proxyPort: 1080 });

// after
new MongoClient('mongodb://db.example.com:27017', { proxyHost: 'proxy', proxyPort: 1080 });

function validateNoProxyWithSocket(uri: string, opts: any) {
  const usesSocket = /%2F.*\.sock/i.test(uri) || typeof opts.socketPath === 'string';
  const usesProxy = Boolean(opts.proxyHost);
  if (usesSocket && usesProxy) {
    throw new Error('Socks5 proxy cannot be combined with a Unix socket target');
  }
}

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

import { MongoInvalidArgumentError } from 'mongodb';
try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /Socks5/.test(e.message)) {
    // drop proxyHost or switch the URI to a TCP host:port
  }
  throw e;
}

When it happens

Trigger: Setting both proxyHost (to enable Socks5) and a socketPath-based hostAddress (Unix socket) in the same connection options. Fires in makeSocks5Connection (src/cmap/connect.ts:502-505) right after parseConnectOptions runs on the proxied options.

Common situations: Mixing a Unix-domain-socket URI ('mongodb://%2Ftmp%2Fmongodb-27017.sock') with proxyHost/proxyPort options; copy-pasting a proxy configuration onto a socket-based local deployment; configuring proxy for a deployment that should connect directly over the socket.

Related errors

• Cannot set both proxyOptions and kmsConnectCallback
• Cannot set both proxyOptions and kmsConnectCallback
• Option "hostAddress" is required
• Must specify proxyHost if other proxy options are passed
• Can only specify both of proxy username/password or neither

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/33cf5bc65d89042a.json. Report an issue: GitHub.