{"record":{"id":"ad15d1a223eab316","repo":"mastra-ai/mastra","slug":"netlify-gateway-token-error","errorCode":"NETLIFY_GATEWAY_TOKEN_ERROR","errorMessage":"Failed to get Netlify AI Gateway token for model ${routerId}: ${error instanceof Error ? error.message : String(error)}","messagePattern":"Failed to get Netlify AI Gateway token for model (.+?): (.+?)","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/llm/model/gateways/netlify.ts","lineNumber":93,"sourceCode":"        category: 'UNKNOWN',\n        text: `Missing NETLIFY_TOKEN environment variable required for model: ${routerId}`,\n      });\n    }\n\n    if (!siteId) {\n      throw new MastraError({\n        id: 'NETLIFY_GATEWAY_NO_SITE_ID',\n        domain: 'LLM',\n        category: 'UNKNOWN',\n        text: `Missing NETLIFY_SITE_ID environment variable required for model: ${routerId}`,\n      });\n    }\n\n    try {\n      const tokenData = await this.getOrFetchToken(siteId, netlifyToken);\n      return tokenData.url.endsWith(`/`) ? tokenData.url.substring(0, tokenData.url.length - 1) : tokenData.url;\n    } catch (error) {\n      throw new MastraError({\n        id: 'NETLIFY_GATEWAY_TOKEN_ERROR',\n        domain: 'LLM',\n        category: 'UNKNOWN',\n        text: `Failed to get Netlify AI Gateway token for model ${routerId}: ${error instanceof Error ? error.message : String(error)}`,\n      });\n    }\n  }\n\n  /**\n   * Get cached token or fetch a new site-specific AI Gateway token from Netlify\n   */\n  private async getOrFetchToken(siteId: string, netlifyToken: string): Promise<TokenData> {\n    const cacheKey = `netlify-token:${siteId}:${netlifyToken}`;\n\n    // Check cache first\n    const cached = (await this.tokenCache.get(cacheKey)) as CachedToken | undefined;\n    if (cached && cached.expiresAt > Date.now() / 1000 + 60) {\n      // Return cached token if it won't expire in the next minute","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/llm/model/gateways/netlify.ts#L75-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded inner error message to identify the root cause","Verify NETLIFY_TOKEN is valid and unexpired with the Netlify API (curl the token endpoint)","Confirm NETLIFY_SITE_ID matches a real site on the token's account","Retry on transient network failures; the token is cached so a retry refetches only when needed"],"exampleFix":"// before\ncatch { /* generic handling */ }\n// after\ntry {\n  const model = new ModelRouterLanguageModel('netlify/openai/gpt-4o');\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'NETLIFY_GATEWAY_TOKEN_ERROR') {\n    console.error('Gateway token issue:', e.message); // inspect inner cause\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (!process.env.NETLIFY_TOKEN || !process.env.NETLIFY_SITE_ID) {\n  throw new Error('NETLIFY_TOKEN and NETLIFY_SITE_ID are required before calling the Netlify gateway');\n}","typeGuard":"function isNetlifyTokenError(e: unknown): e is MastraError {\n  return e instanceof MastraError && e.id === 'NETLIFY_GATEWAY_TOKEN_ERROR';\n}","tryCatchPattern":"try {\n  const model = new ModelRouterLanguageModel('netlify/openai/gpt-4o');\n} catch (e) {\n  if (isNetlifyTokenError(e)) {\n    // e.message contains the inner cause; log and retry with backoff for network cases\n    console.error('Netlify gateway token failure:', e.message);\n  }\n  throw e;\n}","preventionTips":["Verify tokens with the Netlify API during deploy health checks","Rotate tokens before expiry and update all environment secrets","Monitor for this error and alert on repeated token-fetch failures"],"tags":["netlify","authentication","gateway","network"],"backgroundTag":"gateway-token-fetch-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}