mongodb/node-mongodb-native · error · MongoCryptAzureKMSRequestError

[Azure KMS]

Error message

[Azure KMS] ${error.message}

What it means

Wraps a MongoNetworkTimeoutError encountered while contacting the Azure IMDS endpoint into a MongoCryptAzureKMSRequestError, prefixing it with [Azure KMS]. It indicates the HTTP GET to 169.254.169.254 did not complete within the network timeout, not that the response was malformed.

Solutions

1. If off-Azure, supply explicit azure kmsProvider credentials (tenantId/clientId/clientSecret) instead of relying on IMDS.
2. If on Azure, confirm network/security group rules permit traffic to 169.254.169.254 and that the host can reach the metadata service.
3. For containers, ensure the deployment can reach the Azure metadata IP (some CNI setups block link-local).
4. Reduce IMDS call frequency — the driver caches tokens, but rapid MongoClient churn can cause bursts.

Example fix

// before: off-Azure, IMDS unreachable -> [Azure KMS] timeout
const client = new MongoClient(uri, {
  autoEncryption: { kmsProviders: { azure: {} } }
});
// after: explicit SP credentials, no IMDS needed
const client = new MongoClient(uri, {
  autoEncryption: {
    kmsProviders: {
      azure: { tenantId, clientId, clientSecret }
    }
  }
});

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoCryptAzureKMSRequestError && /\[Azure KMS\]/.test(e.message)) {
    // IMDS unreachable; fall back to explicit SP credentials or move to an Azure host
  }
  throw e;
}

When it happens

Trigger: The IMDS HTTP request times out: host off Azure with no route to 169.254.169.254; firewall/NSG blocking the link-local address; IMDS slow to respond under load; the process is in a container without host networking to the metadata service.

Common situations: Running in Docker/Kubernetes without access to the Azure metadata service (169.254.169.254 link-local); NSG rules blocking metadata traffic; Azure IMDS throttling (limit ~5 req/s per identity); local development without Azure identity.

Related errors

• KMS request timed out
• Malformed JSON body in GET request.
• Unable to complete request.
• Malformed response body - missing field `access_token`.
• Malformed response body - missing field `expires_in`.

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

Appendix: source

Thrown at src/client-side-encryption/providers/azure.ts:167

 * @internal
 *
 * `AzureKMSRequestOptions` allows prose tests to modify the http request sent to the idms
 * servers.  This is required to simulate different server conditions.  No options are expected to
 * be set outside of tests.
 *
 * exposed for CSFLE
 * [prose test 18](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/tests#azure-imds-credentials)
 */
export async function fetchAzureKMSToken(
  options: AzureKMSRequestOptions = {}
): Promise<AzureTokenCacheEntry> {
  const { headers, url } = prepareRequest(options);
  try {
    const response = await get(url, { headers });
    return await parseResponse(response);
  } catch (error) {
    if (error instanceof MongoNetworkTimeoutError) {
      throw new MongoCryptAzureKMSRequestError(`[Azure KMS] ${error.message}`);
    }
    throw error;
  }
}

/**
 * @internal
 *
 * @throws Will reject with a `MongoCryptError` if the http request fails or the http response is malformed.
 */
export async function loadAzureCredentials(kmsProviders: KMSProviders): Promise<KMSProviders> {
  const azure = await tokenCache.getToken();
  return { ...kmsProviders, azure };
}

View on GitHub (pinned to dce7939f86)