mongodb/node-mongodb-native · error · MongoCryptAzureKMSRequestError

[Azure KMS] ${error.message}

Error message

[Azure KMS] ${error.message}

What it means

Re-thrown when fetching the Azure IMDS token fails with a MongoNetworkTimeoutError; the original timeout message is wrapped with an '[Azure KMS]' prefix and converted to a MongoCryptAzureKMSRequestError. This surfaces cases where the HTTP GET to 169.254.169.254 did not return in time. Other (non-timeout) errors propagate unchanged.

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

Solutions

1. Confirm reachability with a timed curl: curl -v --max-time 5 -H 'Metadata: true' 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://vault.azure.net'
2. If not on Azure, supply explicit azure KMS provider credentials to bypass IMDS entirely.
3. On Docker/Kubernetes, ensure the network allows link-local traffic (169.254.0.0/16).
4. Raise socketTimeoutMS / timeoutMS if the IMDS hop is legitimately slow.

Example fix

// before: off-Azure host, IMDS times out
const client = new MongoClient(uri, { autoEncryption: { kmsProviders: {}, keyVaultNamespace } });

// after: explicit credentials skip IMDS
const kmsProviders = { azure: { tenantId, clientId, clientSecret } };
const client = new MongoClient(uri, { autoEncryption: { kmsProviders, keyVaultNamespace } });

// Probe IMDS latency before relying on it under a tight timeout.
async function imdsLatencyOk(timeoutMs = 2000): Promise<boolean> {
  const start = Date.now();
  try {
    const controller = new AbortController();
    const t = setTimeout(() => controller.abort(), timeoutMs);
    await fetch('http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://vault.azure.net', { headers: { Metadata: 'true' }, signal: controller.signal });
    clearTimeout(t);
    return Date.now() - start < timeoutMs;
  } catch { return false; }
}

import { MongoCryptAzureKMSRequestError } from 'mongodb';
function isAzureKMSTimeout(e: unknown): boolean {
  return e instanceof MongoCryptAzureKMSRequestError && /^\[Azure KMS\]/.test(e.message);
}

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoCryptAzureKMSRequestError && /\[Azure KMS\]/.test(err.message)) {
    // Switch to explicit azure credentials or raise socketTimeoutMS.
  }
}

When it happens

Trigger: In fetchAzureKMSToken() catch block when the underlying get() rejects with MongoNetworkTimeoutError; happens when the connection to IMDS times out (default socket timeout).

Common situations: IMDS endpoint unreachable or slow (host firewall, Azure platform issue, running off-Azure); tight socketTimeoutMS on the MongoClient flowing into KMS fetch; network namespace/Docker bridge blocking link-local 169.254.169.254; local dev machine that black-holes the address causing slow failure rather than fast refusal.

Related errors

• Malformed JSON body in GET request.
• KMS request timed out
• 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@3366c21a63 (2026-08-04). Data as JSON: /data/errors/19e45c0f22388764.json. Report an issue: GitHub.