mastra-ai/mastra · error · Error

Failed to load templates. Please check your internet connect

Error message

Failed to load templates. Please check your internet connection and try again.

What it means

The catch-all wrapper error from loadTemplates: any failure in fetching or parsing the templates JSON (including error 1008) is logged to console.error and rethrown as this user-facing message. It means the templates list could not be retrieved — usually a connectivity problem, but also any non-OK HTTP response or invalid JSON.

Source

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

  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 => {
    const parts = [];
    if (template.agents?.length) {
      parts.push(`${template.agents.length} ${pluralize(template.agents.length, 'agent')}`);
    }
    if (template.tools?.length) {
      parts.push(`${template.tools.length} ${pluralize(template.tools.length, 'tool')}`);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify internet connectivity and that https://mastra.ai/api/templates.json is reachable, then retry.
2. Check console output for the logged underlying error (the original error is printed via console.error before this throw) to see the true cause.
3. If MASTRA_TEMPLATES_API_URL is set, confirm it returns valid JSON and unset it to test the default endpoint.
4. Bypass the templates listing and scaffold manually (e.g. npx create-mastra with a known template) if the API is down.

try {
  const res = await fetch(process.env.MASTRA_TEMPLATES_API_URL || 'https://mastra.ai/api/templates.json');
  await res.json(); // throws here if response is not valid JSON
} catch { console.warn('Templates API unreachable; proceeding without it'); }

try {
  const templates = await loadTemplates();
} catch (err) {
  // Underlying cause was already logged via console.error by loadTemplates
  console.error('Templates unavailable, check connectivity or MASTRA_TEMPLATES_API_URL');
  const templates: Template[] = []; // fallback to empty list / offline path
}

When it happens

Trigger: Any loadTemplates call (via the templates CLI command) where fetch throws (DNS failure, offline, connection refused), the response is !ok (1008), or response.json() fails to parse.

Common situations: Working offline or on a flaky network; DNS/proxy/firewall blocking mastra.ai; mastra.ai outage; a custom MASTRA_TEMPLATES_API_URL serving HTML or invalid JSON instead of a Template[] JSON body.

Related errors

• HTTP_ERROR
• REQUEST_TIMEOUT
• Failed to fetch templates: ${response.statusText}
• Slack OAuth HTTP error: ${tokenResponse.status} ${tokenRespo
• Failed to stream background tasks: ${response.statusText}

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/373a4cab437b3258. Report an issue: GitHub.