{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connect.ts#L486-L522","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Do not combine proxyHost with a Unix-socket (socketPath) destination — Socks5 only supports TCP targets","If you need to proxy, connect to the MongoDB instance via a TCP host:port instead of a socket path","Remove the proxyHost option when connecting over a local Unix socket"],"exampleFix":"// before: proxy + unix socket is invalid\nnew MongoClient('mongodb://%2Ftmp%2Fmongo.sock/?proxyHost=proxy.local&proxyPort=1080');\n\n// after: proxy requires a TCP destination\nnew MongoClient('mongodb://mongo.internal:27017/?proxyHost=proxy.local&proxyPort=1080');","handlingStrategy":"validation","validationCode":"const hasProxy = !!options.proxyHost;\nconst isSocket = typeof options.hostAddress?.socketPath === 'string';\nif (hasProxy && isSocket) {\n  throw new Error('Socks5 proxy cannot target a Unix socket; use a TCP host:port destination');\n}","typeGuard":"function proxyTargetIsTcp(opts: { proxyHost?: string; hostAddress?: { host?: string; port?: number; socketPath?: string } }): boolean {\n  return typeof opts.hostAddress?.host === 'string' && typeof opts.hostAddress?.port === 'number';\n}","tryCatchPattern":null,"preventionTips":["Never combine proxyHost with a Unix-socket (socketPath) destination","Use TCP host:port when routing MongoDB traffic through a Socks5 proxy","Document that Socks5 is TCP-only in your connection config"],"tags":["connection","socks5","proxy","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}