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 by MongoParseError at src/connection_string.ts:508 when any of `proxyPort`, `proxyUsername`, or `proxyPassword` is set but `proxyHost` is not. The proxy host is the anchor of a proxy configuration; the other fields are meaningless without it.

Solutions

1. Add `proxyHost` (the SOCKS5 proxy hostname) to the URI or options.
2. If you did not intend to use a proxy, remove the stray proxyPort/proxyUsername/proxyPassword options.

Example fix

// before
new MongoClient('mongodb://host:27017/', { proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' })

// after
new MongoClient('mongodb://host:27017/', { proxyHost: 'proxy.internal', proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' })

function assertProxyHostPresent(options = {}) {
  const partial = options.proxyPort || options.proxyUsername || options.proxyPassword;
  if (partial && !options.proxyHost) throw new Error('proxyHost is required when any other proxy option is set.');
}

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /Must specify proxyHost/.test(e.message)) { options.proxyHost = process.env.PROXY_HOST; } else throw e; }

When it happens

Trigger: Options object `{ proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' }` with no proxyHost, or a URI like `...?proxyPort=1080` without `proxyHost=...`.

Common situations: Configuring SOCKS5 proxy access and forgetting the host field; partial secrets loaded from a secret manager that supplies only credentials.

Related errors

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

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

Appendix: 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 dce7939f86)