mastra-ai/mastra · error · MastraError

AZURE_GATEWAY_INVALID_CONFIG

AZURE_GATEWAY_INVALID_CONFIG

Error message

resourceName is required for Azure OpenAI gateway

What it means

The Azure OpenAI gateway's validateConfig, run from the constructor, requires config.resourceName to construct endpoint URLs. If resourceName is missing, a MastraError with id AZURE_GATEWAY_INVALID_CONFIG is thrown immediately when the gateway object is instantiated.

Source

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

      return Reflect.get(target, property, receiver);
    },
  });
}

export class AzureOpenAIGateway extends MastraModelGateway {
  readonly id = 'azure-openai';
  readonly name = 'azure-openai';
  private tokenCache = new InMemoryServerCache();
  private entraIdTokenRequests = new Map<string, Promise<CachedToken>>();

  constructor(private config: AzureOpenAIGatewayConfig) {
    super();
    this.validateConfig();
  }

  private validateConfig(): void {
    if (!this.config.resourceName) {
      throw new MastraError({
        id: 'AZURE_GATEWAY_INVALID_CONFIG',
        domain: 'LLM',
        category: 'UNKNOWN',
        text: 'resourceName is required for Azure OpenAI gateway',
      });
    }

    if (!this.config.apiKey && this.config.authentication?.type !== 'entraId') {
      throw new MastraError({
        id: 'AZURE_GATEWAY_INVALID_CONFIG',
        domain: 'LLM',
        category: 'UNKNOWN',
        text: 'apiKey or Entra ID authentication is required for Azure OpenAI gateway',
      });
    }

    if (this.config.authentication?.type === 'entraId' && !this.config.authentication.credential) {
      throw new MastraError({

View on GitHub (pinned to 75dd419e61)

Solutions

Add resourceName to the gateway config, e.g. new AzureOpenAIGateway({ resourceName: 'my-azure-resource', apiKey: ... }).
Set the corresponding env variable and read it into the config (e.g. process.env.AZURE_RESOURCE_NAME), verifying it is non-empty before construction.
If using a full endpoint URL elsewhere, extract the hostname as resourceName or check the current gateway config schema for the accepted field names.

Example fix

// before
const gateway = new AzureOpenAIGateway({ apiKey: process.env.AZURE_API_KEY });
// after
const gateway = new AzureOpenAIGateway({
  resourceName: process.env.AZURE_RESOURCE_NAME,
  apiKey: process.env.AZURE_API_KEY,
});

Defensive patterns

Strategy: validation

Validate before calling

function assertAzureGatewayConfig(config: { resourceName?: string }): void {
  if (!config.resourceName) {
    throw new Error('Azure OpenAI gateway requires a non-empty resourceName');
  }
}

Type guard

function hasAzureResourceName(
  config: unknown,
): config is { resourceName: string } {
  return typeof config === 'object' && config !== null &&
    typeof (config as any).resourceName === 'string' && (config as any).resourceName.length > 0;
}

Try / catch

try {
  const gateway = new AzureOpenAIGateway(config);
} catch (e) {
  if ((e as any).id === 'AZURE_GATEWAY_INVALID_CONFIG') {
    throw new Error('Azure gateway misconfigured: set AZURE_RESOURCE_NAME and pass it as resourceName', { cause: e });
  }
  throw e;
}

Prevention

Load and assert AZURE_RESOURCE_NAME env at startup before constructing gateways.
Validate the whole gateway config object with a schema (e.g. Zod) before construction.
Keep resourceName and endpoint config in one shared config module so it cannot be omitted.

When it happens

Trigger: Constructing the Azure OpenAI gateway class (constructor calls validateConfig) with a config object that omits the resourceName property.

Common situations: Setting only apiKey or deployment info but forgetting resourceName; loading config from env where the Azure resource name variable is unset; renaming config fields after a version change.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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