mastra-ai/mastra · error · MastraError

NETLIFY_GATEWAY_TOKEN_ERROR

NETLIFY_GATEWAY_TOKEN_ERROR

Error message

Failed to get Netlify AI Gateway token for model ${routerId}: ${error instanceof Error ? error.message : String(error)}

What it means

This wraps any failure from getOrFetchToken — the process of retrieving or fetching a Netlify AI Gateway token — into a MastraError (NETLIFY_GATEWAY_TOKEN_ERROR) when building the gateway URL. The original error's message is preserved in the text, so the root cause (network failure, auth rejection, bad site ID) is inside this message.

Source

Thrown at packages/core/src/llm/model/gateways/netlify.ts:93

        category: 'UNKNOWN',
        text: `Missing NETLIFY_TOKEN environment variable required for model: ${routerId}`,
      });
    }

    if (!siteId) {
      throw new MastraError({
        id: 'NETLIFY_GATEWAY_NO_SITE_ID',
        domain: 'LLM',
        category: 'UNKNOWN',
        text: `Missing NETLIFY_SITE_ID environment variable required for model: ${routerId}`,
      });
    }

    try {
      const tokenData = await this.getOrFetchToken(siteId, netlifyToken);
      return tokenData.url.endsWith(`/`) ? tokenData.url.substring(0, tokenData.url.length - 1) : tokenData.url;
    } catch (error) {
      throw new MastraError({
        id: 'NETLIFY_GATEWAY_TOKEN_ERROR',
        domain: 'LLM',
        category: 'UNKNOWN',
        text: `Failed to get Netlify AI Gateway token for model ${routerId}: ${error instanceof Error ? error.message : String(error)}`,
      });
    }
  }

  /**
   * Get cached token or fetch a new site-specific AI Gateway token from Netlify
   */
  private async getOrFetchToken(siteId: string, netlifyToken: string): Promise<TokenData> {
    const cacheKey = `netlify-token:${siteId}:${netlifyToken}`;

    // Check cache first
    const cached = (await this.tokenCache.get(cacheKey)) as CachedToken | undefined;
    if (cached && cached.expiresAt > Date.now() / 1000 + 60) {
      // Return cached token if it won't expire in the next minute

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the embedded inner error message to identify the root cause
2. Verify NETLIFY_TOKEN is valid and unexpired with the Netlify API (curl the token endpoint)
3. Confirm NETLIFY_SITE_ID matches a real site on the token's account
4. Retry on transient network failures; the token is cached so a retry refetches only when needed

Example fix

// before
catch { /* generic handling */ }
// after
try {
  const model = new ModelRouterLanguageModel('netlify/openai/gpt-4o');
} catch (e) {
  if (e instanceof MastraError && e.id === 'NETLIFY_GATEWAY_TOKEN_ERROR') {
    console.error('Gateway token issue:', e.message); // inspect inner cause
  }
  throw e;
}

if (!process.env.NETLIFY_TOKEN || !process.env.NETLIFY_SITE_ID) {
  throw new Error('NETLIFY_TOKEN and NETLIFY_SITE_ID are required before calling the Netlify gateway');
}

function isNetlifyTokenError(e: unknown): e is MastraError {
  return e instanceof MastraError && e.id === 'NETLIFY_GATEWAY_TOKEN_ERROR';
}

try {
  const model = new ModelRouterLanguageModel('netlify/openai/gpt-4o');
} catch (e) {
  if (isNetlifyTokenError(e)) {
    // e.message contains the inner cause; log and retry with backoff for network cases
    console.error('Netlify gateway token failure:', e.message);
  }
  throw e;
}

When it happens

Trigger: buildUrl calls getOrFetchToken(siteId, netlifyToken) and it rejects: HTTP failure fetching the token, invalid NETLIFY_TOKEN, unknown NETLIFY_SITE_ID, network outage, or malformed gateway response.

Common situations: Expired or revoked Netlify personal access token; site ID not belonging to the account; corporate proxy blocking the token endpoint; transient network errors during deploy-time model calls.

Related errors

• Failed to load GitHub token status (${res.status})
• AuthFailureError(authFailureStatus, error)
• Failed to list projects (${res.status})
• Failed to create access token (${res.status})
• AZURE_DEPLOYMENTS_FETCH_ERROR

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