mastra-ai/mastra · error · Error

Failed to fetch templates: ${response.statusText}

Error message

Failed to fetch templates: ${response.statusText}

What it means

loadTemplates fetches the Mastra templates JSON (https://mastra.ai/api/templates.json, overridable via MASTRA_TEMPLATES_API_URL) and throws this error when the HTTP response is not ok (any 4xx/5xx status). It is immediately caught and rethrown as the generic 'Failed to load templates...' error [1009].

Source

Thrown at packages/cli/src/utils/template-utils.ts:20

export interface Template {
  githubUrl: string;
  title: string;
  slug: string;
  agents: string[];
  mcp: string[];
  tools: string[];
  networks: string[];
  workflows: string[];
}

const TEMPLATES_API_URL = process.env.MASTRA_TEMPLATES_API_URL || 'https://mastra.ai/api/templates.json';

export async function loadTemplates(): Promise<Template[]> {
  try {
    const response = await fetch(TEMPLATES_API_URL);
    if (!response.ok) {
      throw new Error(`Failed to fetch templates: ${response.statusText}`);
    }
    const templates = (await response.json()) as Template[];
    return templates;
  } catch (error) {
    console.error('Error loading templates:', error);
    throw new Error('Failed to load templates. Please check your internet connection and try again.');
  }
}

function pluralize(count: number, singular: string, plural?: string): string {
  return count === 1 ? singular : plural || `${singular}s`;
}

export async function selectTemplate(
  templates: Template[],
  options: { signal?: AbortSignal } = {},
): Promise<Template | null> {
  const choices = templates.map(template => {

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Check https://mastra.ai/api/templates.json is reachable (curl -I) and retry after the outage passes.
  2. If MASTRA_TEMPLATES_API_URL is set, verify it points to a valid templates.json endpoint or unset it to use the default.
  3. Check for proxy/firewall/VPN interference and rate limiting; use the correct network or wait out the rate limit.

Example fix

// before
export MASTRA_TEMPLATES_API_URL=https://internal.example.com/old-templates.json
// 404 -> Failed to fetch templates: Not Found

// after
unset MASTRA_TEMPLATES_API_URL   # fall back to https://mastra.ai/api/templates.json
Defensive patterns

Strategy: retry

Validate before calling

const res = await fetch(TEMPLATES_API_URL, { method: 'HEAD' });
if (!res.ok) throw new Error(`Templates API unavailable: ${res.status}`);

Try / catch

async function loadTemplatesWithRetry(retries = 3) {
  for (let i = 0; i < retries; i++) {
    try { return await loadTemplates(); }
    catch (err) {
      if (i === retries - 1) throw err;
      await new Promise(r => setTimeout(r, 2 ** i * 500));
    }
  }
}

Prevention

When it happens

Trigger: Running the create-mastra templates command (`mastra templates`/create flow) when the templates API returns a non-OK response: 404 (wrong URL), 403 (rate limit/CDN block), 5xx (server outage).

Common situations: MASTRA_TEMPLATES_API_URL pointing at a wrong/removed endpoint; mastra.ai outage or CDN rate limiting; corporate proxy returning 403; offline with a captive portal returning HTML error pages.

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/baea025a9c445e67. Report an issue: GitHub.