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 when exactly one of proxyUsername / proxyPassword is set (connection_string.ts:511-516). The driver requires them as a pair; specifying only one is treated as a misconfiguration because there is no useful 'username-only' or 'password-only' auth mode for the proxy.

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 3366c21a63)

Solutions

1. Provide both proxyUsername and proxyPassword together.
2. Or remove both to use an unauthenticated proxy.
3. Audit your env-var wiring to ensure both variables are present.

Example fix

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

const hasUser = 'proxyUsername' in opts || new URL(uri).searchParams.has('proxyUsername');
const hasPass = 'proxyPassword' in opts || new URL(uri).searchParams.has('proxyPassword');
if (hasUser !== hasPass) {
  throw new Error('Provide both proxyUsername and proxyPassword, or neither');
}

When it happens

Trigger: Options { proxyHost: 'p', proxyUsername: 'u' } (no password) or URI '?proxyHost=p&proxyPassword=secret' (no username).

Common situations: Templating only the proxyPassword from a secret while hardcoding username elsewhere; partial env var population (PROXY_USER set but PROXY_PASS unset).

Related errors

• Must specify proxyHost if other proxy options are passed
• 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/2d1d6f7bc7eb8110.json. Report an issue: GitHub.