Automattic/mongoose · error · MongooseError

Connection operation buffering timed out after ${bufferTimeo

Error message

Connection operation buffering timed out after ${bufferTimeoutMS}ms

What it means

Mongoose buffers operations issued while the connection is still connecting or reconnecting instead of failing immediately, for up to bufferTimeoutMS (default 10000 ms; settable via connect options or schema-level bufferCommands). Connection.prototype._waitForConnect (lib/connection.js:863) rejects every waiting operation with this error when the connection never becomes usable within that window. bufferTimeoutMS: 0 disables buffering entirely — ops then fail immediately while disconnected.

Source

Thrown at lib/connection.js:864

        new Promise(resolve => {
          timeout = setTimeout(
            () => {
              timedOut = true;
              resolve();
            },
            bufferTimeoutMS
          );
        })
      ]);
    }

    if (timedOut) {
      const index = this._queue.indexOf(queueElement);
      if (index !== -1) {
        this._queue.splice(index, 1);
      }
      const message = 'Connection operation buffering timed out after ' + bufferTimeoutMS + 'ms';
      throw new MongooseError(message);
    } else if (timeout != null) {
      // Not strictly necessary, but avoid the extra overhead of creating a new MongooseError
      // in case of success
      clearTimeout(timeout);
    }
  }
};

/*!
 * Get the default buffer timeout for this connection
 */

Connection.prototype._getBufferTimeoutMS = function _getBufferTimeoutMS() {
  if (this.config.bufferTimeoutMS != null) {
    return this.config.bufferTimeoutMS;
  }
  if (this.base?.get('bufferTimeoutMS') != null) {
    return this.base.get('bufferTimeoutMS');

View on GitHub (pinned to 49cdab0136)

Solutions

1. Await connection readiness before issuing ops: await mongoose.connect(uri) or await conn.asPromise() at startup
2. Fix the underlying connectivity (URI, host, port, credentials, network); consider lowering serverSelectionTimeoutMS so the real connection error surfaces sooner
3. If slow startup is expected, raise bufferTimeoutMS in the connect options
4. For fail-fast behavior set bufferTimeoutMS: 0 or the schema option bufferCommands: false

Example fix

// before
mongoose.connect(uri);
await User.findOne(); // buffered; rejects after 10s with 'buffering timed out'

// after
await mongoose.connect(uri);
await User.findOne();

if (mongoose.connection.readyState !== 1) {
  await mongoose.connection.asPromise(); // wait for real connection, or fail with the true cause
}

try {
  await conn.bulkWrite(ops);
} catch (err) {
  if (err instanceof mongoose.Error && /buffering timed out/.test(err.message)) {
    await conn.asPromise(); // surfaces the REAL connection error if unreachable
    return await conn.bulkWrite(ops); // retry once connected
  }
  throw err;
}

When it happens

Trigger: Calling conn.bulkWrite(), Model.find(), conn.startSession(), or any connection-dependent API right after createConnection()/connect() without awaiting it, while the server is unreachable (wrong host/port, firewall, DNS, auth failure) or replica-set discovery exceeds bufferTimeoutMS.

Common situations: Forgot `await mongoose.connect()` before the first query; CI test suites without a running DB service; Atlas cold starts; localhost-vs-127.0.0.1 IPv6 resolution problems; connections dropped mid-run while code keeps querying.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Cannot call `${this.name}.${i}()` before initial connection
• Connection#createClient not implemented by driver
• No connections to database "${name}" found
• The `uri` parameter to `openUri()` must be a string, got "${
• Connection has been closed and destroyed, and cannot be used

AI-assisted analysis of Automattic/mongoose@49cdab0136 (2026-08-21). Data as JSON: /api/errors/3971a319a1180142. Report an issue: GitHub.