mongodb/node-mongodb-native · error · MongoParseError

must be either "true" or "false

Error message

${name} must be either "true" or "false"

What it means

Boolean URI options (tls, ssl, loadBalanced, directConnection, retryWrites, etc.) only accept the literal strings 'true' or 'false', or a real boolean when passed via the options object. getBoolean throws for anything else to avoid silent coercion surprises.

Solutions

1. Use the lowercase literal 'true' or 'false' in the URI.
2. If passing via options object, pass an actual boolean (true/false), not a string.

Example fix

// before
new MongoClient('mongodb://h/db?tls=true&retryWrites=1');
// after
new MongoClient('mongodb://h/db?tls=true&retryWrites=true');

const BOOL_RE = /^(true|false)$/i;
function assertBoolOption(name: string, value: unknown) {
  if (typeof value === 'boolean') return;
  if (typeof value === 'string' && BOOL_RE.test(value)) return;
  throw new Error(`${name} must be 'true' or 'false', got: ${value}`);
}

function isBoolOptionValue(v: unknown): v is boolean | 'true' | 'false' {
  return typeof v === 'boolean' || (typeof v === 'string' && /^(true|false)$/i.test(v));
}

When it happens

Trigger: Passing a URI query value like 'tls=yes', 'ssl=1', 'loadBalanced=TRUE' (uppercase), or 'retryWrites=0' to a boolean option. Also triggered by a boolean option set via the options object with a non-boolean, non-'true'/'false' string.

Common situations: Coming from another driver that accepts '1'/'0' or 'yes'/'no', copy-pasting config from a YAML/ENV that uses different truthiness, or case-sensitivity assumptions.

Related errors

• Cannot have undefined values in key value pairs
• Expected to be stringified int value, got
• All values of tls/ssl must be the same.
• Auth mechanism property ALLOWED_HOSTS is not allowed in the…
• authMechanism requires an authSource of '$external

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

Appendix: source

Thrown at src/connection_string.ts:184

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 {
  const parsedInt = parseInteger(value);
  if (parsedInt != null) {
    return parsedInt;
  }
  throw new MongoParseError(`Expected ${name} to be stringified int value, got: ${value}`);
}

function getUIntFromOptions(name: string, value: unknown): number {
  const parsedValue = getIntFromOptions(name, value);
  if (parsedValue < 0) {
    throw new MongoParseError(`${name} can only be a positive int value, got: ${value}`);
  }
  return parsedValue;
}

View on GitHub (pinned to dce7939f86)