{"record":{"id":"bc067b236ff98c48","repo":"mongodb/node-mongodb-native","slug":"mongoerror-builderrormessage-cause","errorCode":null,"errorMessage":"${MongoError.buildErrorMessage(cause)}","messagePattern":"\\$\\{MongoError\\.buildErrorMessage\\(cause\\)\\}","errorType":"exception","errorClass":"MongoNetworkError","httpStatus":null,"severity":"error","filePath":"src/cmap/connect.ts","lineNumber":532,"sourceCode":"      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\n        host: 'iLoveJavaScript',\n        port: 0,\n        type: 5,\n        userId: options.proxyUsername || undefined,\n        password: options.proxyPassword || undefined\n      }\n    });\n    existingSocket = connection.socket;\n  } catch (cause) {\n    throw new MongoNetworkError(MongoError.buildErrorMessage(cause), { cause });\n  }\n\n  // Finally, now treat the resulting duplex stream as the\n  // socket over which we send and receive wire protocol messages:\n  return await makeSocket({ ...options, existingSocket, proxyHost: undefined });\n}\n","sourceCodeStart":514,"sourceCodeEnd":539,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/connect.ts#L514-L539","documentation":"Thrown as a MongoNetworkError in makeSocks5Connection() when socks.SocksClient.createConnection(...) rejects. The message is derived via MongoError.buildErrorMessage(cause), which extracts cause.message (or joins AggregateError errors, or returns 'empty error message'). The original rejection is attached as cause. This wraps any Socks5-layer failure into a driver network error so it surfaces consistently.","triggerScenarios":"The Socks5 proxy handshake (socks.SocksClient.createConnection) fails: proxy unreachable, proxy refuses authentication, proxy cannot reach the destination, or the connection times out (options.connectTimeoutMS). Only occurs when proxyHost is configured.","commonSituations":"Proxy host/port wrong in the URI; proxy requires auth and proxyUsername/proxyPassword are missing or wrong; the proxy cannot route to the internal MongoDB host; firewall blocks the proxy egress; Socks5 timeout too low.","solutions":["Verify proxyHost and proxyPort (default 1080) are correct and the proxy is reachable","Provide proxyUsername/proxyPassword if the proxy requires authentication","Ensure the proxy can route to the MongoDB destination host:port (check proxy ACLs/firewall)","Increase connectTimeoutMS if the proxy/destination is slow, and inspect error.cause for the underlying Socks5 failure code"],"exampleFix":"// before\nnew MongoClient('mongodb://mongo:27017/?proxyHost=10.0.0.5'); // wrong/no port, no auth\n\n// after\nnew MongoClient('mongodb://mongo:27017/?proxyHost=10.0.0.5&proxyPort=1080&proxyUsername=u&proxyPassword=p&connectTimeoutMS=30000');","handlingStrategy":"try-catch","validationCode":"// validate proxy reachability before connect\nconst net = require('net');\nawait new Promise<void>((resolve, reject) => {\n  const s = net.connect(proxyPort, proxyHost);\n  s.once('connect', () => { s.destroy(); resolve(); });\n  s.once('error', reject);\n});","typeGuard":null,"tryCatchPattern":"try { await client.connect(); } catch (e) {\n  if (e instanceof MongoNetworkError && /socks/i.test(e.cause?.message ?? '')) {\n    // inspect e.cause for Socks5 reply code; fix proxy host/port/credentials\n  }\n  throw e;\n}","preventionTips":["Verify proxyHost/proxyPort and that the proxy is reachable before connecting","Supply proxyUsername/proxyPassword when the proxy requires auth","Confirm the proxy can route to the MongoDB destination (firewall/ACL checks)","Size connectTimeoutMS to the proxy round-trip; inspect cause for the Socks5 error code"],"tags":["connection","socks5","proxy","network"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}