mastra-ai/mastra · error · MastraError

NETLIFY_GATEWAY_NO_SITE_ID

NETLIFY_GATEWAY_NO_SITE_ID

Error message

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

What it means

The Netlify AI Gateway requires both a NETLIFY_TOKEN and a NETLIFY_SITE_ID environment variable to route model requests. This library throws NETLIFY_GATEWAY_NO_SITE_ID from buildUrl when a model routed through the Netlify gateway is used but the site ID is missing, because it cannot construct the gateway URL without it.

Source

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

    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);
      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)}`,
      });
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the NETLIFY_SITE_ID environment variable to your Netlify site ID (netlify sites:list or the site dashboard)
2. Verify the variable is present in the runtime environment (dotenv loaded, CI secrets configured) before constructing the model
3. Confirm you actually intend to use the Netlify gateway; otherwise use a direct provider model config

Example fix

// before
new ModelRouterLanguageModel('netlify/openai/gpt-4o'); // NETLIFY_SITE_ID unset
// after
process.env.NETLIFY_SITE_ID = 'your-site-id';
process.env.NETLIFY_TOKEN = 'your-netlify-token';
new ModelRouterLanguageModel('netlify/openai/gpt-4o');

if (!process.env.NETLIFY_SITE_ID) {
  throw new Error('NETLIFY_SITE_ID must be set before using a Netlify gateway model');
}

try {
  const model = new ModelRouterLanguageModel('netlify/openai/gpt-4o');
} catch (e) {
  if (e instanceof MastraError && e.id === 'NETLIFY_GATEWAY_NO_SITE_ID') {
    console.error('Set NETLIFY_SITE_ID (and NETLIFY_TOKEN) in your environment');
  }
  throw e;
}

When it happens

Trigger: Using a model with the netlify gateway (routerId prefixed for Netlify) while process.env.NETLIFY_SITE_ID is unset or empty when buildUrl is invoked (via baseURL).

Common situations: Deployed or local environments where NETLIFY_TOKEN is set but NETLIFY_SITE_ID was never exported; renamed/typo'd env var (NETLIFY_SITEID); using the gateway in CI without configuring secrets.

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

• Clerk JWKS URI, secret key and publishable key are required,
• Google client ID is required. Provide it in the options or s
• [MastraAuthGoogle] GOOGLE_COOKIE_PASSWORD is required for Go
• Okta domain is required. Provide it in the options or set OK
• Okta client ID is required. Provide it in the options or set

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