{"record":{"id":"1163b731e1c2661b","repo":"mongodb/node-mongodb-native","slug":"kms-request-timed-out","errorCode":null,"errorMessage":"KMS request timed out","messagePattern":"KMS request timed out","errorType":"exception","errorClass":"MongoOperationTimeoutError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/state_machine.ts","lineNumber":496,"sourceCode":"            request.addResponse(buffer.read(bytesNeeded));\n          }\n\n          if (request.bytesNeeded <= 0) {\n            resolve();\n          }\n        });\n      const remainingTimeMS = options?.timeoutContext?.csotEnabled()\n        ? options.timeoutContext.getRemainingTimeMSOrThrow(\n            `KMS request timed out after ${options.timeoutContext.timeoutMS}ms`\n          )\n        : undefined;\n      const timeoutMS = Number.isFinite(remainingTimeMS) ? remainingTimeMS : undefined;\n      kmsRequestTimeout = timeoutMS ? Timeout.expires(timeoutMS) : undefined;\n      await (kmsRequestTimeout\n        ? Promise.race([willResolveKmsRequest, kmsRequestTimeout])\n        : willResolveKmsRequest);\n    } catch (error) {\n      if (TimeoutError.is(error)) throw new MongoOperationTimeoutError('KMS request timed out');\n      throw error;\n    } finally {\n      // There's no need for any more activity on this socket at this point.\n      destroySockets();\n      abortListener?.[kDispose]();\n      kmsRequestTimeout?.clear();\n    }\n  }\n\n  *requests(context: MongoCryptContext, options?: { timeoutContext?: TimeoutContext } & Abortable) {\n    for (\n      let request = context.nextKMSRequest();\n      request != null;\n      request = context.nextKMSRequest()\n    ) {\n      yield this.kmsRequest(request, options);\n    }\n  }","sourceCodeStart":478,"sourceCodeEnd":514,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/state_machine.ts#L478-L514","documentation":"Thrown as a MongoOperationTimeoutError when the KMS HTTP request (AWS/GCP/Azure/local) does not complete before the timeout. With CSOT (Client-Side Operation Timeout) enabled, the remaining operation time is used as the KMS deadline; once exceeded this error is raised from the state machine's KMS request handler.","triggerScenarios":"Wrapping/unwrapping a Customer Master Key over a slow or unreachable KMS endpoint while a timeoutMS/CSOT deadline is active; transient network latency to AWS KMS / Azure Key Vault / GCP KMS; the operation's remaining time (timeoutContext.getRemainingTimeMS) was already near zero when KMS work began.","commonSituations":"KMS endpoint behind a slow proxy or in another region; DNS/TLS slowness to kms.<region>.amazonaws.com; a very small timeoutMS set on the operation leaving no time for the KMS round-trip; saturated network on the DB host.","solutions":["Increase timeoutMS on the operation/connection so the KMS round-trip has enough remaining time.","Place the application closer to the KMS region (same region for AWS KMS / Azure Key Vault / GCP KMS).","Ensure network egress to the KMS endpoint is unblocked and not throttled by a proxy/firewall.","Reduce KMS calls by reusing data encryption keys and the driver's token caching; verify the KMS TLS handshake is fast (no revoked-CA OCSP stalls)."],"exampleFix":"// before: CSOT deadline too tight for KMS round-trip\nawait coll.findOne({}, { timeoutMS: 500 }); // KMS > 500ms -> timeout\n// after: allow headroom for KMS\nawait coll.findOne({}, { timeoutMS: 10000 });","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await coll.findOne({}, { timeoutMS: 10000 });\n} catch (e) {\n  if (e instanceof MongoOperationTimeoutError && /KMS request timed out/.test(e.message)) {\n    // increase timeoutMS and/or co-locate with the KMS region, then retry\n  }\n  throw e;\n}","preventionTips":["Set timeoutMS with headroom for KMS round-trips when CSOT is used.","Keep the application and KMS in the same cloud region.","Reuse DEKs to minimise KMS wrap/unwrap calls."],"tags":["csfle","kms","timeout","network","csot"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}