mastra-ai/mastra · error

Repository URL or path is required

Error message

Repository URL or path is required

What it means

The clone step of the template-builder workflow requires `repo` in its input (AgentBuilderInputSchema output) and throws 'Repository URL or path is required' when inputData.repo is missing or empty. The workflow otherwise infers slug and defaults ref, but repo is the one mandatory identifier of what to clone.

Source

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

  resolveTargetPath,
  mergeGitignoreFiles,
  mergeEnvFiles,
  resolveModel,
} from '../../utils';

type AgentBuilderInputSchemaType = z.infer<typeof AgentBuilderInputSchema>;

// Step 1: Clone template to temp directory
const cloneTemplateStep = createStep({
  id: 'clone-template',
  description: 'Clone the template repository to a temporary directory at the specified ref',
  inputSchema: AgentBuilderInputSchema,
  outputSchema: CloneTemplateResultSchema,
  execute: async ({ inputData }) => {
    const { repo, ref = 'main', slug, targetPath } = inputData;

    if (!repo) {
      throw new Error('Repository URL or path is required');
    }

    // Extract slug from repo URL if not provided
    const inferredSlug =
      slug ||
      repo
        .split('/')
        .pop()
        ?.replace(/\.git$/, '') ||
      'template';

    // Create temporary directory
    const tempDir = await mkdtemp(join(tmpdir(), 'mastra-template-'));

    try {
      // Clone repository
      await gitClone(repo, tempDir);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a repository URL or local path in the input: { repo: 'https://github.com/mastra-ai/templates/...' }
2. If you only have a slug, resolve the repo URL from the templates registry (getMastraTemplate) before starting the workflow
3. Check the input key spelling — it must be `repo`, matching AgentBuilderInputSchema
4. Pre-validate inputs and surface a friendly message before invoking the workflow

Example fix

// before
await templateBuilderWorkflow.start({ triggerData: { slug: 'weather-app', ref: 'main' } });

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

type BuilderInput = { repo?: string; ref?: string; slug?: string; targetPath?: string };
function assertRepo(input: BuilderInput): asserts input is BuilderInput & { repo: string } {
  if (typeof input.repo !== 'string' || input.repo.trim() === '') {
    throw new Error('repo (URL or path) is required to build a template');
  }
}

When it happens

Trigger: Starting the template-builder workflow with input that omits `repo` (only slug/targetPath supplied), or providing an empty string; constructing the input object manually rather than through the tool/UI that normally populates repo.

Common situations: Calling the workflow directly from code with a partial input object; a UI/tool layer passing only the slug; input schema drift so repo exists under another key; test harnesses that build inputs by hand.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Input data not found
• Forecast data not found
• Critical failure in clone step: ${cloneResult.error}
• PROCESSOR_MISSING_MESSAGE_LIST
• Workflow ${workflowId} not found

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