{"id":"f6b41a74f387dad9","repo":"mongodb/node-mongodb-native","slug":"name-must-be-either-true-or-false","errorCode":null,"errorMessage":"${name} must be either \"true\" or \"false\"","messagePattern":"(.+?) must be either \"true\" or \"false\"","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":184,"sourceCode":"function checkTLSOptions(allOptions: CaseInsensitiveMap): void {\n  if (!allOptions) return;\n  const check = (a: string, b: string) => {\n    if (allOptions.has(a) && allOptions.has(b)) {\n      throw new MongoAPIError(`The '${a}' option cannot be used with the '${b}' option`);\n    }\n  };\n  check('tlsInsecure', 'tlsAllowInvalidCertificates');\n  check('tlsInsecure', 'tlsAllowInvalidHostnames');\n}\nfunction getBoolean(name: string, value: unknown): boolean {\n  if (typeof value === 'boolean') return value;\n  switch (value) {\n    case 'true':\n      return true;\n    case 'false':\n      return false;\n    default:\n      throw new MongoParseError(`${name} must be either \"true\" or \"false\"`);\n  }\n}\n\nfunction getIntFromOptions(name: string, value: unknown): number {\n  const parsedInt = parseInteger(value);\n  if (parsedInt != null) {\n    return parsedInt;\n  }\n  throw new MongoParseError(`Expected ${name} to be stringified int value, got: ${value}`);\n}\n\nfunction getUIntFromOptions(name: string, value: unknown): number {\n  const parsedValue = getIntFromOptions(name, value);\n  if (parsedValue < 0) {\n    throw new MongoParseError(`${name} can only be a positive int value, got: ${value}`);\n  }\n  return parsedValue;\n}","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L166-L202","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use exactly 'true' or 'false' (lowercase) for boolean URI options.","Normalize env booleans before building the URI: b ? 'true' : 'false'.","Prefer passing the option as a real boolean in the options object instead of the URI string.","Strip quotes/whitespace from templated values before interpolation."],"exampleFix":"// before\nconst uri = `mongodb://h/db?retryWrites=${process.env.RETRY_WRITES ?? 'yes'}`;\n// after\nconst retryWrites = process.env.RETRY_WRITES === '1';\nnew MongoClient('mongodb://h/db', { retryWrites });","handlingStrategy":"validation","validationCode":"function toBoolUriValue(name: string, value: unknown): 'true' | 'false' {\n  if (typeof value === 'boolean') return value ? 'true' : 'false';\n  if (value === 'true' || value === 'false') return value;\n  throw new Error(`Option ${name} must be 'true' or 'false', got: ${String(value)}`);\n}\nconst uri = `mongodb://h/db?retryWrites=${toBoolUriValue('retryWrites', process.env.RETRY_WRITES ?? true)}`;","typeGuard":"const isLowerBoolString = (v: unknown): v is 'true' | 'false' => v === 'true' || v === 'false';","tryCatchPattern":"try {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoParseError && /must be either .true. or .false./.test(e.message)) {\n    throw new Error('Boolean URI option must be exactly \"true\" or \"false\"');\n  }\n  throw e;\n}","preventionTips":["Normalize env booleans to 'true'/'false' before interpolating into a URI.","Pass booleans via the options object instead of the URI when possible.","Never use 1/0 or yes/no for boolean URI options."],"tags":["connection-string","parsing","config","boolean"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}