mongodb/node-mongodb-native · error · MongoParseError

Proxy options cannot be specified multiple times in the…

Error message

Proxy options cannot be specified multiple times in the connection string

What it means

Thrown by MongoParseError at src/connection_string.ts:523 when any of the four proxy options (`proxyHost`, `proxyPort`, `proxyUsername`, `proxyPassword`) appears more than once in the URI query string. URL options have single-value semantics for proxy settings, so duplicates are rejected.

Solutions

Ensure each proxy option appears at most once in the URI query string.
Prefer passing proxy settings via the MongoClient options object (where later keys naturally override earlier ones) instead of hand-building the query string.

Example fix

// before
new MongoClient('mongodb://host:27017/?proxyHost=a&proxyHost=b')

// after
new MongoClient('mongodb://host:27017/', { proxyHost: 'b', proxyPort: 1080 })

Defensive patterns

Strategy: validation

Validate before calling

function assertNoDupProxyKeys(uri) {
  const qs = uri.split('?')[1] || '';
  const seen = new Set();
  for (const kv of qs.split('&')) {
    const k = kv.split('=')[0];
    if (['proxyHost','proxyPort','proxyUsername','proxyPassword'].includes(k)) {
      if (seen.has(k)) throw new Error(`Proxy option ${k} duplicated in URI.`);
      seen.add(k);
    }
  }
}

Try / catch

try { new MongoClient(uri); } catch (e) { if (e instanceof MongoParseError && /Proxy options cannot be specified multiple times/.test(e.message)) { /* rebuild URI with deduped query string */ } else throw e; }

Prevention

Build query strings with URLSearchParams or an options object rather than string concatenation.
Deduplicate keys before passing the URI to the driver.

When it happens

Trigger: URI `...?proxyHost=a&proxyHost=b`, or `?proxyPort=1080&proxyPort=1081`, etc. Often caused by URL-building libraries that append the same key twice.

Common situations: QueryString string concatenation that appends a default and an override; a config layer merging two URI fragments without deduplication.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:523

    !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'
    );
  }

  mongoOptions.mongoLoggerOptions = MongoLogger.resolveOptions(
    {
      MONGODB_LOG_COMMAND: process.env.MONGODB_LOG_COMMAND,
      MONGODB_LOG_TOPOLOGY: process.env.MONGODB_LOG_TOPOLOGY,
      MONGODB_LOG_SERVER_SELECTION: process.env.MONGODB_LOG_SERVER_SELECTION,
      MONGODB_LOG_CONNECTION: process.env.MONGODB_LOG_CONNECTION,
      MONGODB_LOG_CLIENT: process.env.MONGODB_LOG_CLIENT,
      MONGODB_LOG_ALL: process.env.MONGODB_LOG_ALL,
      MONGODB_LOG_MAX_DOCUMENT_LENGTH: process.env.MONGODB_LOG_MAX_DOCUMENT_LENGTH,
      MONGODB_LOG_PATH: process.env.MONGODB_LOG_PATH
    },
    {
      mongodbLogPath: mongoOptions.mongodbLogPath,
      mongodbLogComponentSeverities: mongoOptions.mongodbLogComponentSeverities,

View on GitHub (pinned to dce7939f86)