mongodb/node-mongodb-native · error · MongoAzureError

Status code returned from the Azure endpoint. Response body

Error message

Status code ${response.status} returned from the Azure endpoint. Response body: ${response.body}

What it means

Thrown by the Azure machine workflow when the HTTP GET to the Azure IMDS endpoint returns a non-200 status code. The error includes the status and response body to help diagnose why Azure refused the token request (auth, identity, audience, or network issues).

Solutions

  1. Read the response body in the error message: 403/404 usually indicate missing/wrong managed identity or audience.
  2. Ensure a system-assigned identity is enabled on the compute resource, or pass the user-assigned clientId as the username.
  3. Confirm network access to the IMDS endpoint (169.254.169.254) and retry; if throttled (429), back off.
Defensive patterns

Strategy: try-catch

Try / catch

try {
  await client.connect();
} catch (e) {
  if (e instanceof MongoAzureError && /Status code/.test(e.message)) {
    const code = Number(e.message.match(/(\d{3})/)?.[1]);
    if (code === 403 || code === 404) {
      // fix managed identity / clientId / audience
    } else if (code === 429 || code >= 500) {
      // transient: retry with backoff
    }
  }
  throw e;
}

Prevention

When it happens

Trigger: getAzureTokenData() issues the metadata request and response.status !== 200. Fires at azure_machine_workflow.ts:47. Common non-200 causes: 403 (identity/permission), 404 (wrong resource path), 429 (throttle), 5xx (Azure outage).

Common situations: No system-assigned managed identity on the VM. User-assigned identity not specified (username/clientId param). TOKEN_RESOURCE/audience rejected by Azure. Azure IMDS temporarily unavailable or throttling. Network/firewall blocking 169.254.169.254.

Related errors

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

Appendix: source

Thrown at src/cmap/auth/mongodb_oidc/azure_machine_workflow.ts:47

  }
  const response = await getAzureTokenData(tokenAudience, username);
  if (!isEndpointResultValid(response)) {
    throw new MongoAzureError(ENDPOINT_RESULT_ERROR);
  }
  return response;
};

/**
 * Hit the Azure endpoint to get the token data.
 */
async function getAzureTokenData(tokenAudience: string, username?: string): Promise<OIDCResponse> {
  const url = new URL(AZURE_BASE_URL);
  addAzureParams(url, tokenAudience, username);
  const response = await get(url, {
    headers: AZURE_HEADERS
  });
  if (response.status !== 200) {
    throw new MongoAzureError(
      `Status code ${response.status} returned from the Azure endpoint. Response body: ${response.body}`
    );
  }
  const result = JSON.parse(response.body);
  return {
    accessToken: result.access_token,
    expiresInSeconds: Number(result.expires_in)
  };
}

/**
 * Determines if a result returned from the endpoint is valid.
 * This means the result is not nullish, contains the access_token required field
 * and the expires_in required field.
 */
function isEndpointResultValid(
  token: unknown
): token is { access_token: unknown; expires_in: unknown } {

View on GitHub (pinned to dce7939f86)