startSession() / buffered operations hang

[andreialecu]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Mongoose version

9.2.4 (also confirmed on 9.3.3)

Node.js version

v24.13.0

MongoDB server version

7.0 (mongodb-memory-server)

Description

connection.startSession() hangs and times out with Connection operation buffering timed out when test frameworks' fake timers are active (e.g. Vitest's vi.useFakeTimers({ toFake: ['Date'] })).

The Date snapshot fix from #14949 (const Date = globalThis.Date at the top of connection.js) correctly protects the readyState getter — it always uses the real Date.now(). However, the heartbeat handler in drivers/node-mongodb-native/connection.js was not updated and still uses the global Date.now():

// drivers/node-mongodb-native/connection.js:481
client.on('serverHeartbeatSucceeded', () => {
  conn._lastHeartbeatAt = Date.now();  // ← uses faked Date!
});

This creates a mismatch:

Component	Date.now() source	Value with fake timers
readyState getter (connection.js)	Snapshotted (real)	e.g. 2026-03-27
Heartbeat handler (native/connection.js)	Global (faked)	e.g. 2025-01-01

The staleness check Date.now() - _lastHeartbeatAt >= heartbeatFrequencyMS * 2 computes realTime - fakedTime, which easily exceeds the 20s threshold → readyState returns disconnected even though the connection is healthy → startSession() buffers → hangs → times out.

Steps to Reproduce

Save as repro.mjs:

import mongoose from "mongoose";
import { MongoMemoryReplSet } from "mongodb-memory-server";

const BUFFER_TIMEOUT_MS = 5_000;

async function main() {
  const replSet = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
  const conn = mongoose.connection;
  await mongoose.connect(replSet.getUri(), { bufferTimeoutMS: BUFFER_TIMEOUT_MS });
  console.log("Connected. readyState:", conn.readyState); // 1

  // Wait for a heartbeat
  if (conn._lastHeartbeatAt == null) {
    await new Promise((r) => {
      conn.client.on("serverHeartbeatSucceeded", function onHB() {
        conn.client.removeListener("serverHeartbeatSucceeded", onHB);
        r();
      });
    });
  }

  // Confirm startSession works
  const ok = await conn.startSession();
  console.log("startSession() works before faking ✓");
  await ok.endSession();

  // Simulate what vi.useFakeTimers({ toFake: ['Date'] }) does
  const RealDate = globalThis.Date;
  const FAKE_TIME = new RealDate("2020-01-01T00:00:00Z").getTime();
  globalThis.Date = class FakeDate extends RealDate {
    constructor(...args) {
      if (args.length === 0) return new RealDate(FAKE_TIME);
      return new RealDate(...args);
    }
    static now() { return FAKE_TIME; }
  };

  // Wait for heartbeat to record _lastHeartbeatAt with faked Date.now()
  await new Promise((r) => {
    conn.client.on("serverHeartbeatSucceeded", function onHB() {
      conn.client.removeListener("serverHeartbeatSucceeded", onHB);
      r();
    });
  });

  console.log("_readyState:", conn._readyState, "(1 = connected)");
  console.log("readyState: ", conn.readyState,  "(0 = falsely disconnected!)");
  console.log("_lastHeartbeatAt:", conn._lastHeartbeatAt, "(faked time)");
  console.log("Real Date.now():  ", RealDate.now());

  // startSession() hangs and times out
  try {
    await conn.startSession();
  } catch (err) {
    console.log("startSession() failed:", err.message);
  }

  // Prove connection was healthy
  globalThis.Date = RealDate;
  conn._lastHeartbeatAt = null;
  const recovered = await conn.startSession();
  console.log("After fix → startSession() works ✓");
  await recovered.endSession();

  await mongoose.disconnect();
  await replSet.stop();
}

main().catch(console.error);

Run: node repro.mjs

Output

Connected. readyState: 1
startSession() works before faking ✓
_readyState: 1 (1 = connected)
readyState:  0 (0 = falsely disconnected!)
_lastHeartbeatAt: 1577836800000 (faked time)
Real Date.now():   1774602664507
startSession() failed: Connection operation buffering timed out after 5000ms
After fix → startSession() works ✓

Expected Behavior

startSession() should work regardless of whether globalThis.Date has been replaced by fake timers, since the readyState getter already uses a snapshotted Date.

Suggested Fix

Add the same Date snapshot to drivers/node-mongodb-native/connection.js so the heartbeat handler also uses the real Date.now():

// At the top of drivers/node-mongodb-native/connection.js
const Date = globalThis.Date;

This ensures both the readyState getter and the heartbeat handler use the same (real) Date, making the staleness check consistent regardless of fake timers.

[andreialecu]

This may actually be more serious than just fake timers. The staleness check has no recovery path for buffered operations.

Even with heartbeatFrequencyMS: 50 (threshold = 100ms), once _lastHeartbeatAt becomes stale and startSession() is called during that window, it hangs forever regardless of how quickly the next heartbeat refreshes _lastHeartbeatAt. The heartbeat fixes the readyState getter, but the already-buffered operation in _queue is never flushed because it's waiting for a connected state change event that never fires (_readyState was 1 the whole time).

Here's a minimal repro without any fake timers:

import mongoose from "mongoose";
import { MongoMemoryReplSet } from "mongodb-memory-server";

async function main() {
  const replSet = await MongoMemoryReplSet.create({ replSet: { count: 1 } });
  await mongoose.connect(replSet.getUri(), {
    bufferTimeoutMS: 5000,
    heartbeatFrequencyMS: 50,
  });
  const conn = mongoose.connection;

  // Wait for connection + first heartbeat
  await new Promise((r) => {
    conn.client.on("serverHeartbeatSucceeded", function onHB() {
      conn.client.removeListener("serverHeartbeatSucceeded", onHB);
      r();
    });
  });

  // Verify everything works
  const s1 = await conn.startSession();
  console.log("startSession() works:", conn.readyState, "(1 = connected)");
  await s1.endSession();

  // Make _lastHeartbeatAt stale (just past the threshold)
  const threshold = conn.client.topology.s.description.heartbeatFrequencyMS * 2;
  conn._lastHeartbeatAt = Date.now() - threshold - 1;
  console.log("readyState after stale heartbeat:", conn.readyState, "(0 = falsely disconnected)");

  // Start a session (will buffer because readyState = 0)
  const result = conn.startSession().then(
    (s) => ({ ok: true, session: s }),
    (err) => ({ ok: false, message: err.message }),
  );

  // Wait for heartbeats to refresh _lastHeartbeatAt (50ms interval, wait 500ms)
  await new Promise((r) => setTimeout(r, 500));
  console.log("readyState after heartbeat refresh:", conn.readyState, "(1 = connected again)");

  // But startSession() still times out: no recovery for buffered operations
  const outcome = await result;
  if (outcome.ok) {
    console.log("startSession() recovered (unexpected)");
    await outcome.session.endSession();
  } else {
    console.log("startSession() hung and timed out:", outcome.message);
  }

  // Prove connection was healthy the whole time
  conn._lastHeartbeatAt = null;
  await conn.db.collection("test").insertOne({ ok: true });
  const doc = await conn.db.collection("test").findOne({});
  console.log("DB operations work:", doc?.ok === true ? "yes" : "no");

  await mongoose.disconnect();
  await replSet.stop();
}

main().catch(console.error);

Output:

startSession() works: 1 (1 = connected)
readyState after stale heartbeat: 0 (0 = falsely disconnected)
readyState after heartbeat refresh: 1 (1 = connected again)
startSession() hung and timed out: Connection operation buffering timed out after 5000ms
DB operations work: yes

So there are two issues:

1. Missing Date snapshot (the original report): drivers/node-mongodb-native/connection.js uses the global Date.now() in the heartbeat handler, not the snapshotted one from connection.js, so fake timers cause _lastHeartbeatAt to be set with the wrong time.

2. No recovery path (this comment): When serverHeartbeatSucceeded refreshes _lastHeartbeatAt and readyState returns to connected, the _queue of buffered operations is never flushed. The buffered operations wait for a state change event that never fires because _readyState never actually changed.

[andreialecu]

For context, this might be the same underlying mechanism behind several previously closed issues:

• v8.7.1 transaction freeze #14949 - "v8.7.1 transaction freeze" (startSession freezes, led to the Date snapshot fix)
• Connection timeout 10000ms when upgraded mongoose from 7.4.5 to 8.7.1 #14971 - "Connection timeout 10000ms when upgraded mongoose from 7.4.5 to 8.7.1"
• Database connection failed after update mongoose from 8.6.4 to 8.7.0 or higher #15015 - "Database connection failed after update mongoose from 8.6.4 to 8.7.0 or higher"
• loadBalanced=true drops connection after a delay and never reconnects #15042 - "loadBalanced=true drops connection after a delay and never reconnects" (led to temporary revert of the staleness check)
• Model init can hang #15201 - "Model init can hang"
• Ready state showing disconnected when using useDb #15635 - "Ready state showing disconnected when using useDb"

All of these may trace back to the staleness check added in #14812 (for #14727).