mastra-ai/mastra · error · MastraError

AZURE_DEPLOYMENTS_FETCH_ERROR

AZURE_DEPLOYMENTS_FETCH_ERROR

Error message

Failed to fetch Azure deployments: ${response.status} ${error}

What it means

The Azure model gateway failed to fetch the list of available deployments from the Azure OpenAI management endpoint. The HTTP response was not ok, and the error includes the status code plus the raw response body for diagnosis. This MastraError surfaces network/auth/config problems with the Azure resource itself.

Source

Thrown at packages/core/src/llm/model/gateways/azure.ts:436

  ): Promise<AzureDeployment[]> {
    const { subscriptionId, resourceGroup, resourceName } = credentials;

    let url: string | undefined =
      `https://management.azure.com/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.CognitiveServices/accounts/${resourceName}/deployments?api-version=2024-10-01`;

    const allDeployments: AzureDeployment[] = [];

    while (url) {
      const response = await fetch(url, {
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
        },
      });

      if (!response.ok) {
        const error = await response.text();
        throw new MastraError({
          id: 'AZURE_DEPLOYMENTS_FETCH_ERROR',
          domain: 'LLM',
          category: 'UNKNOWN',
          text: `Failed to fetch Azure deployments: ${response.status} ${error}`,
        });
      }

      const data = (await response.json()) as AzureDeploymentsResponse;

      allDeployments.push(...data.value);

      url = data.nextLink;
    }

    const successfulDeployments = allDeployments.filter(d => d.properties.provisioningState === 'Succeeded');

    return successfulDeployments;
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Check the status code and body in the error message to identify the cause (401/403 = credentials, 404 = wrong endpoint/resource, 429 = throttling).
Verify the Azure endpoint URL and apiVersion configured on the gateway are correct for your resource.
Verify the Azure OpenAI API key is valid and has access to the resource.
Retry after backoff if status is 429 or 5xx (transient Azure issue).

Example fix

// before
const gw = new MastraAzureGateway({ resource: 'wrong-resource', apiKey: process.env.AZURE_KEY });
await gw.deployments();
// after
const gw = new MastraAzureGateway({ resource: 'my-openai-resource', apiKey: process.env.AZURE_OPENAI_API_KEY });
try {
  await gw.deployments();
} catch (e) {
  console.error('Azure deployments fetch failed:', e); // inspect status in message
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (!process.env.AZURE_OPENAI_API_KEY || !gw.config?.resource) throw new Error('Azure gateway needs resource + API key before fetching deployments');

Try / catch

try {
  const deployments = await gw.deployments();
} catch (e) {
  const m = /Failed to fetch Azure deployments: (\d+)/.exec(e.message);
  if (m && (m[1] === '429' || m[1].startsWith('5'))) await retryWithBackoff(() => gw.deployments());
  else throw e;
}

Prevention

Validate resource name and API key at startup before network calls.
Log status code and response body from the error message for triage.
Retry only on 429/5xx with exponential backoff.
Pin a supported apiVersion for your resource.

When it happens

Trigger: Calling fetchDeployments() (via deployments()) when the Azure API returns a non-2xx response: invalid endpoint/apiVersion, missing or invalid API key, wrong resource name, rate limiting, or network failure reaching the Azure endpoint.

Common situations: Wrong AZURE endpoint hostname or missing deployment resource; expired/rotated API key; using a resource in a region that's down; blocked corporate network; wrong api-version query param.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/31ba72fc1c6be27e. Report an issue: GitHub.