mongodb/node-mongodb-native · error · MongoParseError

Expected ${name} to be stringified int value, got: ${value}

Error message

Expected ${name} to be stringified int value, got: ${value}

What it means

Thrown by getIntFromOptions() when a URI option expected to be an integer cannot be parsed as one. parseInteger rejects non-numeric strings, booleans, objects, NaN, Infinity, and non-integer numbers. The error message names the option and shows the offending value. It is a MongoParseError.

Source

Thrown at src/connection_string.ts:193

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

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) {

View on GitHub (pinned to 3366c21a63)

Solutions

1. Provide a plain integer string, e.g. ?maxPoolSize=10 (milliseconds for timeout options).
2. Strip units and convert before interpolating: String(Number(value)).
3. Default unset numeric env vars to an integer constant.
4. Pass numeric options via the options object as real numbers to avoid string parsing pitfalls.

Example fix

// before
const uri = `mongodb://h/db?connectTimeoutMS=${process.env.TIMEOUT ?? '5s'}`;
// after
const timeoutMs = Number(process.env.TIMEOUT ?? 5000);
new MongoClient('mongodb://h/db', { serverSelectionTimeoutMS: timeoutMs });

function toIntUriValue(name: string, value: unknown): string {
  const n = Number(value);
  if (!Number.isFinite(n) || !Number.isInteger(n)) {
    throw new Error(`Option ${name} must be an integer, got: ${String(value)}`);
  }
  return String(n);
}
const uri = `mongodb://h/db?maxPoolSize=${toIntUriValue('maxPoolSize', process.env.MAX_POOL ?? 10)}`;

const isIntegerLike = (v: unknown): v is number | string => {
  const n = Number(v);
  return Number.isFinite(n) && Number.isInteger(n);
};

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoParseError && /Expected .* to be stringified int/.test(e.message)) {
    throw new Error('A numeric URI option was not a valid integer');
  }
  throw e;
}

When it happens

Trigger: URI like ?maxPoolSize=ten or ?socketTimeoutMS=30s or ?connectTimeoutMS=2.5 (a float that parseInteger rejects) or ?serverSelectionTimeoutMS= (empty); passing a value with units like '100ms' that the driver does not interpret.

Common situations: Templating a numeric env var that is unset (empty string) or has units; copy-pasting values with units from docs of other drivers; locale-specific formatting inserting commas/decimals; JSON config feeding stringified floats.

Related errors

• ${name} can only be a positive 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/b65a76ca667f2843.json. Report an issue: GitHub.