mongodb/node-mongodb-native · error · MongoOperationTimeoutError

KMS request timed out

Error message

KMS request timed out

What it means

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.

Solutions

1. Increase timeoutMS on the operation/connection so the KMS round-trip has enough remaining time.
2. Place the application closer to the KMS region (same region for AWS KMS / Azure Key Vault / GCP KMS).
3. Ensure network egress to the KMS endpoint is unblocked and not throttled by a proxy/firewall.
4. 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).

Example fix

// before: CSOT deadline too tight for KMS round-trip
await coll.findOne({}, { timeoutMS: 500 }); // KMS > 500ms -> timeout
// after: allow headroom for KMS
await coll.findOne({}, { timeoutMS: 10000 });

try {
  await coll.findOne({}, { timeoutMS: 10000 });
} catch (e) {
  if (e instanceof MongoOperationTimeoutError && /KMS request timed out/.test(e.message)) {
    // increase timeoutMS and/or co-locate with the KMS region, then retry
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

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

Related errors

• [Azure KMS]
• Malformed JSON body in GET request.
• Server roundtrip time is greater than the time remaining
• Timed out during server selection
• Unable to complete request.

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/1163b731e1c2661b. Report an issue: GitHub.

Appendix: source

Thrown at src/client-side-encryption/state_machine.ts:496

            request.addResponse(buffer.read(bytesNeeded));
          }

          if (request.bytesNeeded <= 0) {
            resolve();
          }
        });
      const remainingTimeMS = options?.timeoutContext?.csotEnabled()
        ? options.timeoutContext.getRemainingTimeMSOrThrow(
            `KMS request timed out after ${options.timeoutContext.timeoutMS}ms`
          )
        : undefined;
      const timeoutMS = Number.isFinite(remainingTimeMS) ? remainingTimeMS : undefined;
      kmsRequestTimeout = timeoutMS ? Timeout.expires(timeoutMS) : undefined;
      await (kmsRequestTimeout
        ? Promise.race([willResolveKmsRequest, kmsRequestTimeout])
        : willResolveKmsRequest);
    } catch (error) {
      if (TimeoutError.is(error)) throw new MongoOperationTimeoutError('KMS request timed out');
      throw error;
    } finally {
      // There's no need for any more activity on this socket at this point.
      destroySockets();
      abortListener?.[kDispose]();
      kmsRequestTimeout?.clear();
    }
  }

  *requests(context: MongoCryptContext, options?: { timeoutContext?: TimeoutContext } & Abortable) {
    for (
      let request = context.nextKMSRequest();
      request != null;
      request = context.nextKMSRequest()
    ) {
      yield this.kmsRequest(request, options);
    }
  }

View on GitHub (pinned to dce7939f86)