mongodb/node-mongodb-native · error · MongoParseError

Can only specify both of proxy username/password or neither

Error message

Can only specify both of proxy username/password or neither

What it means

Thrown by MongoParseError at src/connection_string.ts:515 when exactly one of `proxyUsername` / `proxyPassword` is set. SOCKS5 auth requires both halves (or neither, for an unauthenticated proxy).

Solutions

  1. Provide both `proxyUsername` and `proxyPassword` together.
  2. If the proxy needs no auth, remove both `proxyUsername` and `proxyPassword`.

Example fix

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

// after
new MongoClient('mongodb://host:27017/', { proxyHost: 'p', proxyPort: 1080, proxyUsername: 'u', proxyPassword: process.env.PROXY_PASS })
Defensive patterns

Strategy: validation

Validate before calling

function assertProxyCredsPaired(options = {}) {
  const u = !!options.proxyUsername, p = !!options.proxyPassword;
  if (u !== p) throw new Error('proxyUsername and proxyPassword must both be set or both omitted.');
}

Try / catch

try { new MongoClient(uri, options); } catch (e) { if (e instanceof MongoParseError && /both of proxy username\/password/.test(e.message)) { /* add the missing half or drop both */ } else throw e; }

Prevention

When it happens

Trigger: Options `{ proxyHost: 'p', proxyUsername: 'u' }` (no password), or `{ proxyHost: 'p', proxyPassword: 'x' }` (no username).

Common situations: Loading the proxy password from an env var that is empty in one environment; mis-typing one of the two option keys.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:515

    }
  }

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

  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,

View on GitHub (pinned to dce7939f86)