{"record":{"id":"19e45c0f22388764","repo":"mongodb/node-mongodb-native","slug":"azure-kms-error-message","errorCode":null,"errorMessage":"[Azure KMS] ${error.message}","messagePattern":"\\[Azure KMS\\] (.+?)","errorType":"exception","errorClass":"MongoCryptAzureKMSRequestError","httpStatus":null,"severity":"error","filePath":"src/client-side-encryption/providers/azure.ts","lineNumber":167,"sourceCode":" * @internal\n *\n * `AzureKMSRequestOptions` allows prose tests to modify the http request sent to the idms\n * servers.  This is required to simulate different server conditions.  No options are expected to\n * be set outside of tests.\n *\n * exposed for CSFLE\n * [prose test 18](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/tests#azure-imds-credentials)\n */\nexport async function fetchAzureKMSToken(\n  options: AzureKMSRequestOptions = {}\n): Promise<AzureTokenCacheEntry> {\n  const { headers, url } = prepareRequest(options);\n  try {\n    const response = await get(url, { headers });\n    return await parseResponse(response);\n  } catch (error) {\n    if (error instanceof MongoNetworkTimeoutError) {\n      throw new MongoCryptAzureKMSRequestError(`[Azure KMS] ${error.message}`);\n    }\n    throw error;\n  }\n}\n\n/**\n * @internal\n *\n * @throws Will reject with a `MongoCryptError` if the http request fails or the http response is malformed.\n */\nexport async function loadAzureCredentials(kmsProviders: KMSProviders): Promise<KMSProviders> {\n  const azure = await tokenCache.getToken();\n  return { ...kmsProviders, azure };\n}\n","sourceCodeStart":149,"sourceCodeEnd":182,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/client-side-encryption/providers/azure.ts#L149-L182","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["If off-Azure, supply explicit azure kmsProvider credentials (tenantId/clientId/clientSecret) instead of relying on IMDS.","If on Azure, confirm network/security group rules permit traffic to 169.254.169.254 and that the host can reach the metadata service.","For containers, ensure the deployment can reach the Azure metadata IP (some CNI setups block link-local).","Reduce IMDS call frequency — the driver caches tokens, but rapid MongoClient churn can cause bursts."],"exampleFix":"// before: off-Azure, IMDS unreachable -> [Azure KMS] timeout\nconst client = new MongoClient(uri, {\n  autoEncryption: { kmsProviders: { azure: {} } }\n});\n// after: explicit SP credentials, no IMDS needed\nconst client = new MongoClient(uri, {\n  autoEncryption: {\n    kmsProviders: {\n      azure: { tenantId, clientId, clientSecret }\n    }\n  }\n});","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoCryptAzureKMSRequestError && /\\[Azure KMS\\]/.test(e.message)) {\n    // IMDS unreachable; fall back to explicit SP credentials or move to an Azure host\n  }\n  throw e;\n}","preventionTips":["Off-Azure, always supply explicit azure kmsProvider credentials.","On Azure, verify NSG/firewall allows 169.254.169.254."],"tags":["csfle","azure","kms","network","timeout"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}