mongodb/node-mongodb-native · error · MongoParseError

Must specify proxyHost if other proxy options are passed

Error message

Must specify proxyHost if other proxy options are passed

What it means

Thrown when proxyPort, proxyUsername, or proxyPassword is set but proxyHost is missing (connection_string.ts:504-509). proxyHost is the anchor of the SOCKS/HTTP proxy configuration; without it the other fields are uninterpretable, so the driver refuses to construct an incomplete proxy spec.

Source

Thrown at src/connection_string.ts:508

      urlOptions.has('srvServiceName') ||
      objectOptions.has('srvServiceName');

    if (userSpecifiedSrvOptions) {
      throw new MongoParseError(
        'Cannot use srvMaxHosts or srvServiceName with a non-srv connection string'
      );
    }
  }

  if (mongoOptions.directConnection && mongoOptions.hosts.length !== 1) {
    throw new MongoParseError('directConnection option requires exactly one host');
  }

  if (
    !mongoOptions.proxyHost &&
    (mongoOptions.proxyPort || mongoOptions.proxyUsername || mongoOptions.proxyPassword)
  ) {
    throw new MongoParseError('Must specify proxyHost if other proxy options are passed');
  }

  if (
    (mongoOptions.proxyUsername && !mongoOptions.proxyPassword) ||
    (!mongoOptions.proxyUsername && mongoOptions.proxyPassword)
  ) {
    throw new MongoParseError('Can only specify both of proxy username/password or neither');
  }

  const proxyOptions = ['proxyHost', 'proxyPort', 'proxyUsername', 'proxyPassword'].map(
    key => urlOptions.get(key) ?? []
  );

  if (proxyOptions.some(options => options.length > 1)) {
    throw new MongoParseError(
      'Proxy options cannot be specified multiple times in the connection string'
    );
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Add proxyHost to the URI or options whenever any other proxy option is present.
2. Double-check spelling: proxyHost, proxyPort, proxyUsername, proxyPassword.
3. If you don't need a proxy, remove all proxy options.

Example fix

// before
const c = new MongoClient(uri, { proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' });
// after
const c = new MongoClient(uri, { proxyHost: 'proxy.example', proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' });

const proxyKeys = ['proxyPort', 'proxyUsername', 'proxyPassword'];
const anyProxySecondary = proxyKeys.some(k => k in opts || new URL(uri).searchParams.has(k));
if (anyProxySecondary && !('proxyHost' in opts) && !new URL(uri).searchParams.has('proxyHost')) {
  throw new Error('proxyHost is required when any other proxy option is set');
}

When it happens

Trigger: URI like 'mongodb://host/?proxyPort=1080&proxyUsername=foo' or options { proxyPort: 1080 } without proxyHost.

Common situations: Building proxy options conditionally (e.g. setting proxyPort only when behind a corporate proxy) and forgetting the host; typos like proxyHot vs proxyHost.

Related errors

• Can only specify both of proxy username/password or neither
• Proxy options cannot be specified multiple times in the conn
• Cannot set both proxyOptions and kmsConnectCallback
• Cannot set both proxyOptions and kmsConnectCallback
• Can only make Socks5 connections to TCP hosts

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