No Mastra units (agents, workflows, tools) found in template

Error message

No Mastra units (agents, workflows, tools) found in template.
          Possible causes:
          - Template may not follow standard Mastra structure
          - AI agent couldn't analyze template files (model/token limits)
          - Template is empty or in wrong branch

          Debug steps:
          - Check template has files in src/mastra/ directories
          - Try a different branch
          - Check template repository structure manually

What it means

After cloning a template and running AI-assisted discovery of Mastra units (agents, workflows, tools), the template-builder workflow throws this detailed error when zero units were found. It indicates the analysis produced an empty unit list — either the template has no src/mastra structure, or the AI analysis step failed to identify units within model/token limits.

Source

Thrown at packages/agent-builder/src/workflows/template-builder/template-builder.ts:302

      // Add MCP servers
      template.mcp?.forEach((mcpId: { name: string; file: string }) => {
        units.push({ kind: 'mcp-server', id: mcpId.name, file: mcpId.file });
      });

      // Add networks
      template.networks?.forEach((networkId: { name: string; file: string }) => {
        units.push({ kind: 'network', id: networkId.name, file: networkId.file });
      });

      // Add other files
      template.other?.forEach((otherId: { name: string; file: string }) => {
        units.push({ kind: 'other', id: otherId.name, file: otherId.file });
      });

      console.info('Discovered units:', JSON.stringify(units, null, 2));

      if (units.length === 0) {
        throw new Error(`No Mastra units (agents, workflows, tools) found in template.
          Possible causes:
          - Template may not follow standard Mastra structure
          - AI agent couldn't analyze template files (model/token limits)
          - Template is empty or in wrong branch

          Debug steps:
          - Check template has files in src/mastra/ directories
          - Try a different branch
          - Check template repository structure manually`);
      }

      return {
        units,
        success: true,
      };
    } catch (error) {
      console.error('Failed to discover units:', error);
      return {

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the repository actually is a Mastra template with files under src/mastra/ (agents, workflows, tools)
Try a different `ref`/branch — the error message itself suggests this
Inspect the repo manually and confirm agents/workflows/tools exist and are structured conventionally
Use a stronger/valid model for the discovery step (see error 837) — analysis failures may have caused the empty list
Check run logs/Studio traces for the 'Discovered units' line to see what the analysis found before concluding the template is invalid

Example fix

// before
await builder.start({ triggerData: { repo: 'https://github.com/user/random-repo', ref: 'main' } });

// after
await builder.start({
  triggerData: { repo: 'https://github.com/mastra-ai/template-weather-app', ref: 'main' }, // real Mastra template
});

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync, readdirSync } from 'node:fs';
import { join } from 'node:path';
// after cloning targetPath:
const mastraDir = join(targetPath, 'src', 'mastra');
if (!existsSync(mastraDir)) {
  throw new Error(`Target repo has no src/mastra directory; not a Mastra template`);
}

Try / catch

try {
  await builder.start({ triggerData: { repo, ref } });
} catch (e) {
  if (e instanceof Error && e.message.includes('No Mastra units')) {
    // verify src/mastra structure, try another branch/ref, or use a known Mastra template
  } else throw e;
}

Prevention

Only point the builder at repositories with a standard src/mastra layout
Confirm the chosen branch contains the unit files before running
Review the 'Discovered units' log line to distinguish empty templates from analysis failures
Use a capable model for template analysis to avoid token-limit failures

When it happens

Trigger: Cloning a repository that is not a Mastra template (no src/mastra directories); pointing at a wrong branch that lacks unit files; the discovery agent returning empty/partial output because of token limits or a bad model; template files failing to be read during analysis.

Common situations: Using the builder against a random/non-Mastra repo; a template restructured so agents/workflows/tools no longer live in src/mastra; discovery model failing silently on large repos; cloning `main` when the Mastra code is on another branch.

Related errors

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