{"record":{"id":"3971a319a1180142","repo":"Automattic/mongoose","slug":"connection-operation-buffering-timed-out-after-b","errorCode":null,"errorMessage":"Connection operation buffering timed out after ${bufferTimeoutMS}ms","messagePattern":"Connection operation buffering timed out after (.+?)ms","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"error","filePath":"lib/connection.js","lineNumber":864,"sourceCode":"        new Promise(resolve => {\n          timeout = setTimeout(\n            () => {\n              timedOut = true;\n              resolve();\n            },\n            bufferTimeoutMS\n          );\n        })\n      ]);\n    }\n\n    if (timedOut) {\n      const index = this._queue.indexOf(queueElement);\n      if (index !== -1) {\n        this._queue.splice(index, 1);\n      }\n      const message = 'Connection operation buffering timed out after ' + bufferTimeoutMS + 'ms';\n      throw new MongooseError(message);\n    } else if (timeout != null) {\n      // Not strictly necessary, but avoid the extra overhead of creating a new MongooseError\n      // in case of success\n      clearTimeout(timeout);\n    }\n  }\n};\n\n/*!\n * Get the default buffer timeout for this connection\n */\n\nConnection.prototype._getBufferTimeoutMS = function _getBufferTimeoutMS() {\n  if (this.config.bufferTimeoutMS != null) {\n    return this.config.bufferTimeoutMS;\n  }\n  if (this.base?.get('bufferTimeoutMS') != null) {\n    return this.base.get('bufferTimeoutMS');","sourceCodeStart":846,"sourceCodeEnd":882,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/connection.js#L846-L882","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Await connection readiness before issuing ops: await mongoose.connect(uri) or await conn.asPromise() at startup","Fix the underlying connectivity (URI, host, port, credentials, network); consider lowering serverSelectionTimeoutMS so the real connection error surfaces sooner","If slow startup is expected, raise bufferTimeoutMS in the connect options","For fail-fast behavior set bufferTimeoutMS: 0 or the schema option bufferCommands: false"],"exampleFix":"// before\nmongoose.connect(uri);\nawait User.findOne(); // buffered; rejects after 10s with 'buffering timed out'\n\n// after\nawait mongoose.connect(uri);\nawait User.findOne();","handlingStrategy":"retry","validationCode":"if (mongoose.connection.readyState !== 1) {\n  await mongoose.connection.asPromise(); // wait for real connection, or fail with the true cause\n}","typeGuard":null,"tryCatchPattern":"try {\n  await conn.bulkWrite(ops);\n} catch (err) {\n  if (err instanceof mongoose.Error && /buffering timed out/.test(err.message)) {\n    await conn.asPromise(); // surfaces the REAL connection error if unreachable\n    return await conn.bulkWrite(ops); // retry once connected\n  }\n  throw err;\n}","preventionTips":["await mongoose.connect() before the first query and before app.listen()","Expose mongoose.connection.readyState in readiness probes","Set bufferTimeoutMS explicitly in connect options; use 0 for fail-fast behavior","Treat this error as a symptom — always investigate why the connection never opened (URI, credentials, network)"],"tags":["connection","timeout","buffering","startup"],"backgroundTag":"operation-buffering-timeout","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}