{"id":"33cf5bc65d89042a","repo":"mongodb/node-mongodb-native","slug":"can-only-make-socks5-connections-to-tcp-hosts","errorCode":null,"errorMessage":"Can only make Socks5 connections to TCP hosts","messagePattern":"Can only make Socks5 connections to TCP hosts","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cmap/connect.ts","lineNumber":504,"sourceCode":"}\n\nasync function makeSocks5Connection(options: MakeConnectionOptions): Promise<Stream> {\n  const hostAddress = HostAddress.fromHostPort(\n    options.proxyHost ?? '', // proxyHost is guaranteed to set here\n    options.proxyPort ?? 1080\n  );\n\n  // First, connect to the proxy server itself:\n  const rawSocket = await makeSocket({\n    ...options,\n    hostAddress,\n    tls: false,\n    proxyHost: undefined\n  });\n\n  const destination = parseConnectOptions(options) as net.TcpNetConnectOpts;\n  if (typeof destination.host !== 'string' || typeof destination.port !== 'number') {\n    throw new MongoInvalidArgumentError('Can only make Socks5 connections to TCP hosts');\n  }\n\n  socks ??= loadSocks();\n\n  let existingSocket: Stream;\n\n  try {\n    // Then, establish the Socks5 proxy connection:\n    const connection = await socks.SocksClient.createConnection({\n      existing_socket: rawSocket,\n      timeout: options.connectTimeoutMS,\n      command: 'connect',\n      destination: {\n        host: destination.host,\n        port: destination.port\n      },\n      proxy: {\n        // host and port are ignored because we pass existing_socket","sourceCodeStart":486,"sourceCodeEnd":522,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/connect.ts#L486-L522","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Do not combine proxyHost with a Unix socket path; remove proxyHost/proxyPort when connecting via socketPath.","If you must go through Socks5, target a TCP host:port instead of a Unix socket.","Re-check the URI scheme: use mongodb://host:port with proxy options, not a percent-encoded socket path."],"exampleFix":"// before\nnew MongoClient('mongodb://%2Ftmp%2Fmongodb.sock', { proxyHost: 'proxy', proxyPort: 1080 });\n\n// after\nnew MongoClient('mongodb://db.example.com:27017', { proxyHost: 'proxy', proxyPort: 1080 });","handlingStrategy":"validation","validationCode":"function validateNoProxyWithSocket(uri: string, opts: any) {\n  const usesSocket = /%2F.*\\.sock/i.test(uri) || typeof opts.socketPath === 'string';\n  const usesProxy = Boolean(opts.proxyHost);\n  if (usesSocket && usesProxy) {\n    throw new Error('Socks5 proxy cannot be combined with a Unix socket target');\n  }\n}","typeGuard":"function isTcpTarget(opts: { host?: string; port?: number; socketPath?: string }): boolean {\n  return typeof opts.host === 'string' && typeof opts.port === 'number' && !opts.socketPath;\n}","tryCatchPattern":"import { MongoInvalidArgumentError } from 'mongodb';\ntry {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /Socks5/.test(e.message)) {\n    // drop proxyHost or switch the URI to a TCP host:port\n  }\n  throw e;\n}","preventionTips":["Never combine proxyHost/proxyPort with a Unix-socket connection string.","When configuring a proxy, use a host:port URI target.","Keep proxy configuration in a separate env var set from local socket-based dev URIs."],"tags":["socks5","proxy","configuration","connection"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}