mongodb/node-mongodb-native · error · MongoNetworkError

${MongoError.buildErrorMessage(cause)}

Error message

${MongoError.buildErrorMessage(cause)}

What it means

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.

Source

Thrown at src/cmap/connect.ts:532

      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
        host: 'iLoveJavaScript',
        port: 0,
        type: 5,
        userId: options.proxyUsername || undefined,
        password: options.proxyPassword || undefined
      }
    });
    existingSocket = connection.socket;
  } catch (cause) {
    throw new MongoNetworkError(MongoError.buildErrorMessage(cause), { cause });
  }

  // Finally, now treat the resulting duplex stream as the
  // socket over which we send and receive wire protocol messages:
  return await makeSocket({ ...options, existingSocket, proxyHost: undefined });
}

View on GitHub (pinned to dce7939f86)

Solutions

1. Verify proxyHost and proxyPort (default 1080) are correct and the proxy is reachable
2. Provide proxyUsername/proxyPassword if the proxy requires authentication
3. Ensure the proxy can route to the MongoDB destination host:port (check proxy ACLs/firewall)
4. Increase connectTimeoutMS if the proxy/destination is slow, and inspect error.cause for the underlying Socks5 failure code

Example fix

// before
new MongoClient('mongodb://mongo:27017/?proxyHost=10.0.0.5'); // wrong/no port, no auth

// after
new MongoClient('mongodb://mongo:27017/?proxyHost=10.0.0.5&proxyPort=1080&proxyUsername=u&proxyPassword=p&connectTimeoutMS=30000');

// validate proxy reachability before connect
const net = require('net');
await new Promise<void>((resolve, reject) => {
  const s = net.connect(proxyPort, proxyHost);
  s.once('connect', () => { s.destroy(); resolve(); });
  s.once('error', reject);
});

try { await client.connect(); } catch (e) {
  if (e instanceof MongoNetworkError && /socks/i.test(e.cause?.message ?? '')) {
    // inspect e.cause for Socks5 reply code; fix proxy host/port/credentials
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Can only make Socks5 connections to TCP hosts
• Timed out
• Cannot set both proxyOptions and kmsConnectCallback
• Unable to connect to `mongocryptd`, please make sure it is r
• Cannot set both proxyOptions and kmsConnectCallback

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