mongodb/node-mongodb-native · error · MongoParseError

${name} can only be a positive int value, got: ${value}

Error message

${name} can only be a positive int value, got: ${value}

What it means

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.

Source

Thrown at src/connection_string.ts:199

    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;
}

function* entriesFromString(value: string): Generator<[string, string]> {
  if (value === '') {
    return;
  }
  const keyValuePairs = value.split(',');
  for (const keyValue of keyValuePairs) {
    const [key, value] = keyValue.split(/:(.*)/);
    if (value == null) {
      throw new MongoParseError('Cannot have undefined values in key value pairs');
    }

    yield [key, value];
  }
}

View on GitHub (pinned to 3366c21a63)

Solutions

1. Use a non-negative integer for unsigned options, or omit the option to accept the default.
2. Clamp computed values: Math.max(0, value).
3. Represent 'disabled' by removing the option rather than passing -1.
4. Add a runtime assert that unsigned options are >= 0 in your config loader.

Example fix

// before
const uri = `mongodb://h/db?maxStalenessSeconds=${staleness ?? -1}`;
// after
const opts = {};
if (staleness && staleness > 0) opts.maxStalenessSeconds = staleness;
new MongoClient('mongodb://h/db', opts);

function toUIntUriValue(name: string, value: unknown): string {
  const n = Number(value);
  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
    throw new Error(`Option ${name} must be a non-negative integer, got: ${String(value)}`);
  }
  return String(n);
}

const isNonNegativeInt = (v: unknown): v is number =>
  typeof v === 'number' && Number.isInteger(v) && v >= 0;

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoParseError && /can only be a positive int value/.test(e.message)) {
    throw new Error('An unsigned URI option received a negative value');
  }
  throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Expected ${name} to be stringified int value, got: ${value}
• ${name} must be either "true" or "false"
• 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/2217379d9eff4670.json. Report an issue: GitHub.