What causes "Failed to fetch from Netlify: ${response.statusText}" in mastra-ai/mastra?

Check network connectivity to https://api.netlify.com/api/v1/ai-gateway/providers (curl it) and retry — transient 5xx/429 often resolves on retry.

mastra-ai/mastra · error · Error

Failed to fetch from Netlify: ${response.statusText}

Error message

Failed to fetch from Netlify: ${response.statusText}

What it means

NetlifyGateway.fetchProviders() calls Netlify's public API (https://api.netlify.com/api/v1/ai-gateway/providers) to discover the AI Gateway provider/model catalog. If the HTTP response is not ok, it throws this error embedding response.statusText. This is a plain Error thrown during gateway registry population, before any model resolution.

Source

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

  token: string;
  url: string;
  expiresAt: number;
}

interface TokenData {
  token: string;
  url: string;
}

export class NetlifyGateway extends MastraModelGateway {
  readonly id = 'netlify';
  readonly name = 'Netlify AI Gateway';
  private tokenCache = new InMemoryServerCache();

  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
    const response = await fetch('https://api.netlify.com/api/v1/ai-gateway/providers');
    if (!response.ok) {
      throw new Error(`Failed to fetch from Netlify: ${response.statusText}`);
    }
    const data = (await response.json()) as NetlifyResponse;
    const config: ProviderConfig = {
      apiKeyEnvVar: ['NETLIFY_TOKEN', 'NETLIFY_SITE_ID'],
      apiKeyHeader: 'Authorization',
      name: `Netlify`,
      gateway: `netlify`,
      models: [],
      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 };

View on GitHub (pinned to 75dd419e61)

Solutions

Check network connectivity to https://api.netlify.com/api/v1/ai-gateway/providers (curl it) and retry — transient 5xx/429 often resolves on retry.
If behind a proxy/firewall, configure HTTPS_PROXY / NODE_EXTRA_CA_CERTS or allowlist api.netlify.com.
Deregister the netlify gateway (use only the gateways you need) if your environment can't reach Netlify and you don't use Netlify models.
Log response.status (not just statusText) and wrap the registry fetch with retry/backoff to tolerate transient failures.

Example fix

// before
const gateways = [new ModelsDevGateway(), new NetlifyGateway()];
// after (skip netlify when unreachable)
const gateways = process.env.NETLIFY_TOKEN
  ? [new ModelsDevGateway(), new NetlifyGateway()]
  : [new ModelsDevGateway()];

Defensive patterns

Strategy: retry

Validate before calling

async function netlifyProvidersReachable() {
  try {
    const res = await fetch('https://api.netlify.com/api/v1/ai-gateway/providers');
    return res.ok;
  } catch {
    return false;
  }
}
// register NetlifyGateway only if netlifyProvidersReachable()

Type guard

function isOkResponse(res: Response): res is Response & { ok: true } {
  return res.ok;
}

Try / catch

try {
  const providers = await netlifyGateway.fetchProviders();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to fetch from Netlify')) {
    console.warn('Netlify provider catalog unavailable; continuing without netlify gateway');
  } else {
    throw e;
  }
}

Prevention

Wrap gateway registration in a reachability probe so offline/air-gapped environments skip netlify.
Add retry with exponential backoff around external catalog fetches.
Log response.status alongside statusText (statusText can be empty in fetch).
In CI, allowlist api.netlify.com or explicitly disable gateways you don't use.

When it happens

Trigger: Any gateway registry refresh that includes the 'netlify' gateway when the Netlify providers endpoint returns a non-2xx status: network outage/DNS failure reaching api.netlify.com, Netlify API 5xx, rate limiting, TLS/proxy interception returning an error page, or a corporate firewall blocking the request.

Common situations: Running Mastra in an offline or air-gapped CI environment; behind a proxy that blocks api.netlify.com; transient Netlify API outage; aggressive polling triggering rate limits; Docker containers without external network access.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — 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/e218ccca30ea299f. Report an issue: GitHub.