mongodb/node-mongodb-native · error · MongoParseError

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

Error message

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

What it means

Thrown by getBoolean() when parsing a URI option that must be boolean but whose string value is neither 'true' nor 'false'. URI options arrive as strings; the driver coerces recognized boolean options (tls/ssl, loadBalanced, directConnection, retryWrites, etc.) and rejects anything else with a MongoParseError naming the option.

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

Solutions

1. Use exactly 'true' or 'false' (lowercase) for boolean URI options.
2. Normalize env booleans before building the URI: b ? 'true' : 'false'.
3. Prefer passing the option as a real boolean in the options object instead of the URI string.
4. Strip quotes/whitespace from templated values before interpolation.

Example fix

// before
const uri = `mongodb://h/db?retryWrites=${process.env.RETRY_WRITES ?? 'yes'}`;
// after
const retryWrites = process.env.RETRY_WRITES === '1';
new MongoClient('mongodb://h/db', { retryWrites });

function toBoolUriValue(name: string, value: unknown): 'true' | 'false' {
  if (typeof value === 'boolean') return value ? 'true' : 'false';
  if (value === 'true' || value === 'false') return value;
  throw new Error(`Option ${name} must be 'true' or 'false', got: ${String(value)}`);
}
const uri = `mongodb://h/db?retryWrites=${toBoolUriValue('retryWrites', process.env.RETRY_WRITES ?? true)}`;

const isLowerBoolString = (v: unknown): v is 'true' | 'false' => v === 'true' || v === 'false';

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoParseError && /must be either .true. or .false./.test(e.message)) {
    throw new Error('Boolean URI option must be exactly "true" or "false"');
  }
  throw e;
}

When it happens

Trigger: URI like ?retryWrites=yes or ?tls=1 or ?loadBalanced=TRUE (uppercase) or ?directConnection=''; passing a number string '0'/'1'; whitespace or quotes around the value.

Common situations: Building a URI from config values that use 1/0 or yes/no; copy-pasting from documentation that used a different style; templating a boolean from an env var without normalizing; URL-encoding introducing stray characters.

Related errors

• Expected ${name} to be stringified int value, got: ${value}
• ${name} can only be a positive int value, got: ${value}
• Cannot have undefined values in key value pairs
• URI option "${key}" cannot appear more than once in the conn
• URI option "${key}" cannot be specified with no value

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