{"id":"2217379d9eff4670","repo":"mongodb/node-mongodb-native","slug":"name-can-only-be-a-positive-int-value-got-v","errorCode":null,"errorMessage":"${name} can only be a positive int value, got: ${value}","messagePattern":"(.+?) can only be a positive int value, got: (.+?)","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":199,"sourceCode":"    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}\n\nfunction* entriesFromString(value: string): Generator<[string, string]> {\n  if (value === '') {\n    return;\n  }\n  const keyValuePairs = value.split(',');\n  for (const keyValue of keyValuePairs) {\n    const [key, value] = keyValue.split(/:(.*)/);\n    if (value == null) {\n      throw new MongoParseError('Cannot have undefined values in key value pairs');\n    }\n\n    yield [key, value];\n  }\n}","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L181-L217","documentation":"Thrown by getUIntFromOptions() when an option that must be a non-negative integer (unsigned) receives a negative value. It first calls getIntFromOptions (so non-integers throw the sibling error), then rejects values < 0. Applies to options like maxConnecting, maxStalenessSeconds, wtimeoutMS, srvMaxHosts, etc. It is a MongoParseError.","triggerScenarios":"URI like ?maxStalenessSeconds=-1 or ?wtimeoutMS=-500; a templated value computed as a negative number due to a subtraction bug; passing -1 to mean 'unlimited' (the driver does not honor that convention for these options).","commonSituations":"Using -1 as a sentinel for 'disabled' (valid for some options like minPoolSize=0 but not for unsigned ones); arithmetic that underflows when an input is missing; copy-pasting a value from a context where negatives were allowed.","solutions":["Use a non-negative integer for unsigned options, or omit the option to accept the default.","Clamp computed values: Math.max(0, value).","Represent 'disabled' by removing the option rather than passing -1.","Add a runtime assert that unsigned options are >= 0 in your config loader."],"exampleFix":"// before\nconst uri = `mongodb://h/db?maxStalenessSeconds=${staleness ?? -1}`;\n// after\nconst opts = {};\nif (staleness && staleness > 0) opts.maxStalenessSeconds = staleness;\nnew MongoClient('mongodb://h/db', opts);","handlingStrategy":"validation","validationCode":"function toUIntUriValue(name: string, value: unknown): string {\n  const n = Number(value);\n  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {\n    throw new Error(`Option ${name} must be a non-negative integer, got: ${String(value)}`);\n  }\n  return String(n);\n}","typeGuard":"const isNonNegativeInt = (v: unknown): v is number =>\n  typeof v === 'number' && Number.isInteger(v) && v >= 0;","tryCatchPattern":"try {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoParseError && /can only be a positive int value/.test(e.message)) {\n    throw new Error('An unsigned URI option received a negative value');\n  }\n  throw e;\n}","preventionTips":["Never use -1 as a sentinel for unsigned options; omit the key instead.","Clamp computed values with Math.max(0, n).","Validate unsigned options >= 0 in your config loader."],"tags":["connection-string","parsing","config","integer"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}