mongodb/node-mongodb-native · error · MongoRuntimeError

Limit must be less than the number of items

Error message

Limit must be less than the number of items

What it means

Thrown by the shuffle() helper when its `limit` argument exceeds the number of items in the sequence. shuffle() is an internal Fisher-Yates utility used to randomize server/SRV-record ordering for load distribution; the contract is that limit must be <= items.length. A violation is a programming error inside the driver, not user input, and surfaces as a MongoRuntimeError.

Source

Thrown at src/utils.ts:1052

      return true;
    }
  }

  return false;
}

/**
 * Fisher–Yates Shuffle
 *
 * Reference: https://bost.ocks.org/mike/shuffle/
 * @param sequence - items to be shuffled
 * @param limit - Defaults to `0`. If nonzero shuffle will slice the randomized array e.g, `.slice(0, limit)` otherwise will return the entire randomized array.
 */
export function shuffle<T>(sequence: Iterable<T>, limit = 0): Array<T> {
  const items = Array.from(sequence); // shallow copy in order to never shuffle the input

  if (limit > items.length) {
    throw new MongoRuntimeError('Limit must be less than the number of items');
  }

  let remainingItemsToShuffle = items.length;
  const lowerBound = limit % items.length === 0 ? 1 : items.length - limit;
  while (remainingItemsToShuffle > lowerBound) {
    // Pick a remaining element
    const randomIndex = Math.floor(Math.random() * remainingItemsToShuffle);
    remainingItemsToShuffle -= 1;

    // And swap it with the current element
    const swapHold = items[remainingItemsToShuffle];
    items[remainingItemsToShuffle] = items[randomIndex];
    items[randomIndex] = swapHold;
  }

  return limit % items.length === 0 ? items : items.slice(lowerBound);
}

View on GitHub (pinned to 3366c21a63)

Solutions

1. Upgrade to the latest driver patch release; if the error reproduces on the latest version, file a driver bug with the topology details and stack trace.
2. If it correlates with a specific cluster shape (e.g. single host, all-non-empty SRV set), capture that context for the bug report.
3. As a workaround, avoid the triggering configuration (e.g. different SRV host) until patched.

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoRuntimeError && /Limit must be less than the number of items/.test(err.message)) {
    // internal driver defect; capture topology context and report
    throw new Error('Driver internal error during server selection shuffle', { cause: err });
  }
  throw err;
}

When it happens

Trigger: Internal call site passing a limit larger than the candidate set (e.g. asking to shuffle more servers/SRV records than were discovered). Not reachable through a specific public API option.

Common situations: A regression in SDAM or SRV polling code computing an invalid limit; unusual cluster topologies exercising an untested shuffle path; an internal caller miscounting candidates after a topology change.

Related errors

• ConnectionPool.clear() called in load balanced mode with no
• Service generations are required in load balancer mode.
• ServerDescription must be provided with a non-empty address
• unexpected topology type: ${topologyDescription.type} (this
• Options for SrvPoller must exist and include srvHost

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