mastra-ai/mastra · error · Error

Invalid Mastra project

Error message

Invalid Mastra project

What it means

Thrown by `mastra create --github <url>` after validateGitHubProject() reports the remote repository is not a recognizable Mastra project. The CLI first clones/inspects the GitHub repo and runs structural validation; if validation.isValid is false it prints each validation error and aborts. This prevents scaffolding from a repo that lacks the required Mastra project structure.

Source

Thrown at packages/cli/src/commands/create/create.ts:744

    const selected = await runCreatePrompt(signal => selectTemplate(templates, { signal }));
    if (!selected) cancelCreate();
    return selected;
  }

  if (typeof template !== 'string') {
    throw new Error('No template selected');
  }

  const githubUrl = parseGitHubRepositoryUrl(template);
  if (githubUrl) {
    const spinner = p.spinner();
    spinner.start('Validating GitHub repository...');
    const validation = await validateGitHubProject(githubUrl);
    if (!validation.isValid) {
      spinner.stop('Validation failed');
      p.log.error('This does not appear to be a valid Mastra project:');
      validation.errors.forEach(error => p.log.error(`  - ${error}`));
      throw new Error('Invalid Mastra project');
    }
    spinner.stop('Valid Mastra project ✓');
    return createFromGitHubUrl(githubUrl);
  }
  if (looksLikeGitHubUrl(template)) {
    throw new Error('Invalid GitHub repository URL. Use https://github.com/<owner>/<repository>.');
  }

  const templates = await loadTemplates();
  const found = findTemplateByName(templates, template);
  if (!found) {
    p.log.error(`Template "${template}" not found. Available templates:`);
    templates.forEach(availableTemplate =>
      p.log.info(`  - ${availableTemplate.title} (use: ${availableTemplate.slug.replace('template-', '')})`),
    );
    throw new Error(`Template "${template}" not found`);
  }
  return found;

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Read the '- <error>' lines printed above the throw — validateGitHubProject lists exactly which structural checks failed.
  2. Verify the URL points at the intended Mastra starter/template repository (owner and repo name).
  3. Open the repo and confirm package.json contains mastra dependencies (e.g. @mastra/core) and the expected mastra project files.
  4. If the repo is yours, restructure it to match the Mastra starter layout or start from an official template instead.

Example fix

// before
mastra create --github https://github.com/me/my-random-repo
// after
mastra create --github https://github.com/mastra-ai/starter-template
Defensive patterns

Strategy: validation

Validate before calling

const m = url.match(/^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(\.git)?\/?$/);
if (!m) throw new Error('Not a GitHub repo URL');
// then confirm the repo is a Mastra project (has mastra deps/config) before passing to `mastra create`

Type guard

function isGitHubRepoUrl(v: string): boolean {
  return /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+(\.git)?$/.test(v);
}

Try / catch

try {
  await createFromGitHubUrl(url);
} catch (e) {
  if ((e as Error).message === 'Invalid Mastra project') {
    console.error('Repo is not a Mastra project — use an official Mastra starter or fix the repo layout.');
  }
}

Prevention

When it happens

Trigger: Running `mastra create` with a GitHub URL whose repository fails validateGitHubProject() — e.g. missing package.json with mastra dependencies, no mastra config, or wrong directory layout.

Common situations: Pointing the CLI at a fork, a fork with renamed packages, a plain JS repo with an unrelated Mastra-like setup, a repo on a non-default branch layout, or a URL typo landing on the wrong repository.

Related errors

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