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 internal shuffle() utility when the requested limit exceeds the number of items in the sequence. shuffle() performs a partial Fisher-Yates shuffle that requires limit <= items.length. Raised as MongoRuntimeError. This helper is used internally by SDAM (e.g. shuffling the server list for load distribution) and is not part of the public API.

Solutions

1. Upgrade the driver to the latest stable version.
2. Report the full stack trace to the NODE driver Jira project with topology details.
3. If reproducible, reduce the cluster topology change rate (avoid rapid add/remove of nodes).

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoRuntimeError && /Limit must be less than/.test(e.message)) {
    // internal SDAM error: upgrade driver and report
  } else throw e;
}

When it happens

Trigger: Internal SDAM code calling shuffle() with a limit larger than the available server/seed list. Not triggered by user-facing options directly; would indicate a driver bug in server-selection or topology description logic.

Common situations: Nearly never seen by users. Theoretically reachable if the topology's server count shrinks between computing a limit and calling shuffle(), or via a driver internal bug.

Related errors

• Argument "setName" is required if connected to a replica set
• Argument "size" must be a non-negative number
• ClientSession requires a MongoClient
• ClientSession requires a ServerSessionPool
• ConnectionPool.clear() called in load balanced mode with no…

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/104b2a611f3bb642. Report an issue: GitHub.

Appendix: 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 dce7939f86)