mastra-ai/mastra · error · MastraError

NETLIFY_GATEWAY_NO_TOKEN

NETLIFY_GATEWAY_NO_TOKEN

Error message

Missing NETLIFY_TOKEN environment variable required for model: ${routerId}

What it means

NetlifyGateway.buildUrl() exchanges your NETLIFY_SITE_ID + NETLIFY_TOKEN for a short-lived site-scoped AI Gateway token and URL. Before doing so it checks that NETLIFY_TOKEN is present (from the optional envVars argument or process.env). If missing, it throws a MastraError with id NETLIFY_GATEWAY_NO_TOKEN, since the token exchange cannot be authenticated.

Source

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

      docUrl: 'https://docs.netlify.com/build/ai-gateway/overview/',
    };
    // Convert Netlify format to our standard format
    for (const [providerId, provider] of Object.entries(data.providers)) {
      for (const model of provider.models) {
        config.models.push(`${providerId}/${model}`);
      }
    }
    // Return with gateway ID as key - registry generator will detect this and avoid doubling the prefix
    return { netlify: config };
  }

  async buildUrl(routerId: string, envVars?: typeof process.env): Promise<string> {
    // Check for Netlify site ID first (for token exchange)
    const siteId = envVars?.['NETLIFY_SITE_ID'] || process.env['NETLIFY_SITE_ID'];
    const netlifyToken = envVars?.['NETLIFY_TOKEN'] || process.env['NETLIFY_TOKEN'];

    if (!netlifyToken) {
      throw new MastraError({
        id: 'NETLIFY_GATEWAY_NO_TOKEN',
        domain: 'LLM',
        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);

View on GitHub (pinned to 75dd419e61)

Solutions

Set process.env.NETLIFY_TOKEN to a Netlify personal access token with access to the AI Gateway-enabled site before model resolution.
Also set NETLIFY_SITE_ID — it is required next (a separate NETLIFY_GATEWAY_NO_SITE_ID error follows).
If your token lives under a different name (e.g. NETLIFY_AUTH_TOKEN), copy it: process.env.NETLIFY_TOKEN ??= process.env.NETLIFY_AUTH_TOKEN.
Ensure dotenv/config (or your platform's secret injection) runs before Mastra initializes; verify in serverless that the env vars are attached to the function.
If you don't intend to use Netlify models, avoid netlify/* model ids so the netlify gateway path is never invoked.

Example fix

// before
const agent = new Agent({ model: 'netlify/openai/gpt-4o' });
// after
import 'dotenv/config';
if (!process.env.NETLIFY_TOKEN || !process.env.NETLIFY_SITE_ID) {
  throw new Error('NETLIFY_TOKEN and NETLIFY_SITE_ID are required for netlify models');
}
const agent = new Agent({ model: 'netlify/openai/gpt-4o' });

Defensive patterns

Strategy: validation

Validate before calling

import 'dotenv/config';
if (!process.env.NETLIFY_TOKEN) throw new Error('NETLIFY_TOKEN is required for netlify models');
if (!process.env.NETLIFY_SITE_ID) throw new Error('NETLIFY_SITE_ID is required for netlify models');

Type guard

function hasNetlifyCredentials(env: NodeJS.ProcessEnv = process.env): env is NodeJS.ProcessEnv & { NETLIFY_TOKEN: string; NETLIFY_SITE_ID: string } {
  return typeof env.NETLIFY_TOKEN === 'string' && env.NETLIFY_TOKEN.length > 0 &&
         typeof env.NETLIFY_SITE_ID === 'string' && env.NETLIFY_SITE_ID.length > 0;
}

Try / catch

import { MastraError } from '@mastra/core';
try {
  const model = mastra.getModel('netlify/openai/gpt-4o');
} catch (e) {
  if (e instanceof MastraError && e.id === 'NETLIFY_GATEWAY_NO_TOKEN') {
    console.error('Set NETLIFY_TOKEN (and NETLIFY_SITE_ID) to use netlify models');
  }
  throw e;
}

Prevention

Set both NETLIFY_TOKEN and NETLIFY_SITE_ID in .env and in your deployment's secret store.
Guard against the NETLIFY_AUTH_TOKEN vs NETLIFY_TOKEN naming mismatch.
Load dotenv at the very first import so vars exist before gateway model resolution.
If not using Netlify models, never reference netlify/* model ids so this gateway path stays dormant.
Fail fast at startup with a hasNetlifyCredentials() assert when netlify models are configured.

When it happens

Trigger: Resolving any netlify/<provider>/<model> model (which awaits buildUrl for the gateway base URL) when neither the envVars param nor process.env contains NETLIFY_TOKEN. Also hit by getApiKey, which performs the same check.

Common situations: Deploying to serverless/CI where Netlify secrets were never configured; using NETLIFY_AUTH_TOKEN instead of NETLIFY_TOKEN (wrong name); .env not loaded at startup; running locally against Netlify models without a Netlify account token; team members without AI Gateway-enabled sites omitting the variables.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — 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/1540b9a609f075bf. Report an issue: GitHub.