{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/client-side-encryption/state_machine.ts#L478-L514","documentation":"Thrown as a MongoOperationTimeoutError from the CSFLE KMS request path when the TLS connection to the KMS provider (AWS KMS, Azure, GCP, etc.) does not complete within the remaining operation timeout budget. With CSOT (Client-Side Operation Timeout) enabled, the timeoutContext.getRemainingTimeMSOrThrow() surfaces this message; the same string is reused for the kmsConnectCallback path. It indicates the encryption operation's overall deadline was consumed before the KMS round-trip finished.","triggerScenarios":"In state_machine.ts kmsRequest() when a TimeoutError fires during connect (kmsConnectCallback path, line 400) or during the data exchange (line 496); also via getRemainingTimeMSOrThrow when csot is enabled.","commonSituations":"Setting timeoutMS on the MongoClient/operation too low for KMS latency; network path to KMS (kms.<region>.amazonaws.com, vault.azure.net, etc.) slow or blocked; custom kmsConnectCallback that doesn't respect the supplied timeoutMS; proxy adding latency to the KMS TLS handshake; KMS endpoint temporarily degraded.","solutions":["Raise the operation timeout (timeoutMS) or the socketTimeoutMS to accommodate KMS round-trip latency.","Verify network reachability and latency to the KMS endpoint from the application host.","If using a custom kmsConnectCallback, honor the timeoutMS argument and abort the connection on expiry.","Move the workload closer to the KMS region (same AWS/Azure region as the CMK).","If using CSOT, ensure timeoutMS is not inherited from a too-aggressive default."],"exampleFix":"// before\nconst client = new MongoClient(uri, { timeoutMS: 1000, autoEncryption: { ... } });\n\n// after: give KMS enough time\nconst client = new MongoClient(uri, { timeoutMS: 10000, autoEncryption: { ... } });","handlingStrategy":"retry","validationCode":"// Ensure your timeout budget exceeds expected KMS latency.\nfunction saneTimeout(kmsRegionPingMs: number): number {\n  return Math.max(5000, kmsRegionPingMs * 10);\n}","typeGuard":"import { MongoOperationTimeoutError } from 'mongodb';\nfunction isKMSTimeout(e: unknown): boolean {\n  return e instanceof MongoOperationTimeoutError && e.message === 'KMS request timed out';\n}","tryCatchPattern":"try {\n  await collection.insertOne({ ssn: encrypt(value) });\n} catch (err) {\n  if (err instanceof MongoOperationTimeoutError && err.message === 'KMS request timed out') {\n    // raise timeoutMS or check connectivity to the KMS endpoint, then retry\n  }\n}","preventionTips":["Set timeoutMS generously when CSFLE/KMS is involved (>=5s).","Run app and KMS in the same cloud region.","If using kmsConnectCallback, honor its timeoutMS and signal."],"tags":["csfle","kms","timeout","csot","network","queryable-encryption"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}