{"record":{"id":"ffd4dd95f9f8c407","repo":"mastra-ai/mastra","slug":"failed-to-fetch-mastra-templates-error-instance","errorCode":null,"errorMessage":"Failed to fetch Mastra templates: ${error instanceof Error ? error.message : String(error)}","messagePattern":"Failed to fetch Mastra templates: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent-builder/src/utils.ts","lineNumber":241,"sourceCode":"    workflows: string[];\n    tools: string[];\n  }>\n> {\n  try {\n    const response = await fetch('https://mastra.ai/api/templates.json');\n    const data = (await response.json()) as Array<{\n      slug: string;\n      title: string;\n      description: string;\n      githubUrl: string;\n      tags: string[];\n      agents: string[];\n      workflows: string[];\n      tools: string[];\n    }>;\n    return data;\n  } catch (error) {\n    throw new Error(`Failed to fetch Mastra templates: ${error instanceof Error ? error.message : String(error)}`);\n  }\n}\n\n// Helper to get a specific template by slug\nexport async function getMastraTemplate(slug: string) {\n  const templates = await fetchMastraTemplates();\n  const template = templates.find(t => t.slug === slug);\n  if (!template) {\n    throw new Error(`Template \"${slug}\" not found. Available templates: ${templates.map(t => t.slug).join(', ')}`);\n  }\n  return template;\n}\n\n// Git commit tracking utility\nexport async function logGitState(targetPath: string, label: string): Promise<void> {\n  try {\n    // Skip if not a git repo\n    if (!(await isInsideGitRepo(targetPath))) return;","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/agent-builder/src/utils.ts#L223-L259","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nconst templates = await getMastraTemplate(slug); // throws raw fetch error\n\n// after\ntry {\n  const templates = await getMastraTemplate(slug);\n} catch (e) {\n  console.error('Check network access to the Mastra templates endpoint:', e.message);\n  return null;\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"async function getTemplatesSafe() {\n  for (let attempt = 0; attempt < 3; attempt++) {\n    try {\n      return await fetchMastraTemplates();\n    } catch (e) {\n      if (attempt === 2) throw e; // message already includes root cause\n      await new Promise(r => setTimeout(r, 500 * 2 ** attempt));\n    }\n  }\n}","preventionTips":["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"],"tags":["network","http","external-api"],"backgroundTag":"http-request-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}