mongodb/node-mongodb-native · error · MongoAPIError

The '${a}' option cannot be used with the '${b}' option

Error message

The '${a}' option cannot be used with the '${b}' option

What it means

Thrown by checkTLSOptions() when mutually exclusive TLS options are both present. Specifically, tlsInsecure cannot be combined with tlsAllowInvalidCertificates, and tlsInsecure cannot be combined with tlsAllowInvalidHostnames, because tlsInsecure already implies both. It is a MongoAPIError raised during option processing after options are merged from URI and object.

Source

Thrown at src/connection_string.ts:170

    throw new MongoParseError('Cannot combine replicaSet option with srvMaxHosts');
  }

  validateLoadBalancedOptions(hostAddresses, options, true);

  return hostAddresses;
}

/**
 * Checks if TLS options are valid
 *
 * @param allOptions - All options provided by user or included in default options map
 * @throws MongoAPIError if TLS options are invalid
 */
function checkTLSOptions(allOptions: CaseInsensitiveMap): void {
  if (!allOptions) return;
  const check = (a: string, b: string) => {
    if (allOptions.has(a) && allOptions.has(b)) {
      throw new MongoAPIError(`The '${a}' option cannot be used with the '${b}' option`);
    }
  };
  check('tlsInsecure', 'tlsAllowInvalidCertificates');
  check('tlsInsecure', 'tlsAllowInvalidHostnames');
}
function getBoolean(name: string, value: unknown): boolean {
  if (typeof value === 'boolean') return value;
  switch (value) {
    case 'true':
      return true;
    case 'false':
      return false;
    default:
      throw new MongoParseError(`${name} must be either "true" or "false"`);
  }
}

function getIntFromOptions(name: string, value: unknown): number {

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove tlsInsecure and keep only the granular flag you need.
2. Or remove the granular flags (tlsAllowInvalidCertificates/tlsAllowInvalidHostnames) and keep tlsInsecure.
3. Audit both the URI and the options object passed to new MongoClient — the conflict can come from either source.
4. Re-run with only one TLS relaxation strategy to confirm the error clears.

Example fix

// before
new MongoClient('mongodb://h/db?tlsInsecure=true&tlsAllowInvalidCertificates=false');
// after
new MongoClient('mongodb://h/db?tlsAllowInvalidCertificates=false');

function assertTlsOptionsOk(opts: Record<string, unknown>): void {
  if (opts.tlsInsecure && (opts.tlsAllowInvalidCertificates != null || opts.tlsAllowInvalidHostnames != null)) {
    throw new Error('tlsInsecure cannot be combined with tlsAllowInvalidCertificates/tlsAllowInvalidHostnames');
  }
}
assertTlsOptionsOk(resolvedOptions);

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoAPIError && /option cannot be used with/.test(e.message)) {
    throw new Error('Conflicting TLS options in connection config');
  }
  throw e;
}

When it happens

Trigger: URI like ...?tlsInsecure=true&tlsAllowInvalidCertificates=false; passing tlsInsecure via the options object while the URI carries tlsAllowInvalidHostnames; a config template that sets tlsInsecure plus a per-env override setting one of the granular flags.

Common situations: Hardening TLS and forgetting to remove the broad tlsInsecure flag; merging two config sources (URI + options) that each set a different TLS relaxation; copy-pasting a debug connection string that had tlsInsecure plus a granular override.

Related errors

• Option "srvHost" must not be empty
• Multiple text records not allowed
• Text record may only set any of: ${VALID_TXT_RECORDS.join(',
• Cannot have empty URI params in DNS TXT Record
• Cannot combine replicaSet option with srvMaxHosts

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