mongodb/node-mongodb-native · error · MongoOperationTimeoutError

KMS request timed out

Error message

KMS request timed out

What it means

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.

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 3366c21a63)

Solutions

1. Raise the operation timeout (timeoutMS) or the socketTimeoutMS to accommodate KMS round-trip latency.
2. Verify network reachability and latency to the KMS endpoint from the application host.
3. If using a custom kmsConnectCallback, honor the timeoutMS argument and abort the connection on expiry.
4. Move the workload closer to the KMS region (same AWS/Azure region as the CMK).
5. If using CSOT, ensure timeoutMS is not inherited from a too-aggressive default.

Example fix

// before
const client = new MongoClient(uri, { timeoutMS: 1000, autoEncryption: { ... } });

// after: give KMS enough time
const client = new MongoClient(uri, { timeoutMS: 10000, autoEncryption: { ... } });

// Ensure your timeout budget exceeds expected KMS latency.
function saneTimeout(kmsRegionPingMs: number): number {
  return Math.max(5000, kmsRegionPingMs * 10);
}

import { MongoOperationTimeoutError } from 'mongodb';
function isKMSTimeout(e: unknown): boolean {
  return e instanceof MongoOperationTimeoutError && e.message === 'KMS request timed out';
}

try {
  await collection.insertOne({ ssn: encrypt(value) });
} catch (err) {
  if (err instanceof MongoOperationTimeoutError && err.message === 'KMS request timed out') {
    // raise timeoutMS or check connectivity to the KMS endpoint, then retry
  }
}

When it happens

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

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

Related errors

• [Azure KMS] ${error.message}
• Malformed JSON body in GET request.
• Server roundtrip time is greater than the time remaining
• Timed out during server selection
• Cannot set both proxyOptions and kmsConnectCallback

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/1163b731e1c2661b.json. Report an issue: GitHub.