Failed to fetch Mastra templates: ${error instanceof Error ?

Error message

Failed to fetch Mastra templates: ${error instanceof Error ? error.message : String(error)}

What it means

fetchMastraTemplates fetches the Mastra templates listing from a remote endpoint. Any failure during that fetch/parse (network error, non-OK status, invalid JSON, DNS failure) is rethrown as 'Failed to fetch Mastra templates: <original message>'. The original error's message is embedded, so the root cause is always appended.

Source

Thrown at packages/agent-builder/src/utils.ts:241

    workflows: string[];
    tools: string[];
  }>
> {
  try {
    const response = await fetch('https://mastra.ai/api/templates.json');
    const data = (await response.json()) as Array<{
      slug: string;
      title: string;
      description: string;
      githubUrl: string;
      tags: string[];
      agents: string[];
      workflows: string[];
      tools: string[];
    }>;
    return data;
  } catch (error) {
    throw new Error(`Failed to fetch Mastra templates: ${error instanceof Error ? error.message : String(error)}`);
  }
}

// Helper to get a specific template by slug
export async function getMastraTemplate(slug: string) {
  const templates = await fetchMastraTemplates();
  const template = templates.find(t => t.slug === slug);
  if (!template) {
    throw new Error(`Template "${slug}" not found. Available templates: ${templates.map(t => t.slug).join(', ')}`);
  }
  return template;
}

// Git commit tracking utility
export async function logGitState(targetPath: string, label: string): Promise<void> {
  try {
    // Skip if not a git repo
    if (!(await isInsideGitRepo(targetPath))) return;

View on GitHub (pinned to 75dd419e61)

Solutions

Check the embedded cause message in the error and fix it (DNS, proxy, TLS, HTTP status)
Verify network access: curl the templates endpoint and confirm a 200 with JSON
If behind a proxy, set HTTPS_PROXY/HTTP_PROXY env vars so Node's fetch can route out
Retry later if the templates service is temporarily down
Upgrade @mastra/agent-builder if the endpoint's response schema changed (version mismatch)

Example fix

// before
const templates = await getMastraTemplate(slug); // throws raw fetch error

// after
try {
  const templates = await getMastraTemplate(slug);
} catch (e) {
  console.error('Check network access to the Mastra templates endpoint:', e.message);
  return null;
}

Defensive patterns

Strategy: retry

Try / catch

async function getTemplatesSafe() {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await fetchMastraTemplates();
    } catch (e) {
      if (attempt === 2) throw e; // message already includes root cause
      await new Promise(r => setTimeout(r, 500 * 2 ** attempt));
    }
  }
}

Prevention

Guarantee network egress to the templates endpoint (CI, firewalls, proxies)
Set HTTPS_PROXY when behind a corporate proxy
Retry transient failures with exponential backoff
Keep the agent-builder package updated if the endpoint response shape changes

When it happens

Trigger: Calling fetchMastraTemplates directly or via getMastraTemplate/the `templates` tool when the templates endpoint is unreachable, returns HTTP 4xx/5xx, DNS resolution fails, or the response body is not the expected { templates: [{ slug, ... agents, workflows, tools }] } JSON.

Common situations: Offline or firewalled environments (CI without network egress); corporate proxies blocking the request; the templates service being down or its response shape changed after an upgrade; TLS issues in restricted environments.

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