mastra-ai/mastra · critical

Critical failure in clone step: ${cloneResult.error}

Error message

Critical failure in clone step: ${cloneResult.error}

What it means

After the cloneTemplateStep runs, the workflow checks shouldAbortWorkflow(cloneResult); if the clone step reported a failure it throws a fatal 'Critical failure in clone step' error carrying the step's own error message. This aborts the entire template build before analysis/unit-discovery run, because nothing downstream can proceed without a cloned template directory.

Source

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

  steps: [
    cloneTemplateStep,
    analyzePackageStep,
    discoverUnitsStep,
    orderUnitsStep,
    packageMergeStep,
    installStep,
    programmaticFileCopyStep,
    intelligentMergeStep,
    validationAndFixStep,
  ],
})
  .then(cloneTemplateStep)
  .map(async ({ getStepResult }) => {
    const cloneResult = getStepResult(cloneTemplateStep);

    // Check for failure in clone step
    if (shouldAbortWorkflow(cloneResult)) {
      throw new Error(`Critical failure in clone step: ${cloneResult.error}`);
    }

    return cloneResult;
  })
  .parallel([analyzePackageStep, discoverUnitsStep])
  .map(async ({ getStepResult }) => {
    const analyzeResult = getStepResult(analyzePackageStep);
    const discoverResult = getStepResult(discoverUnitsStep);

    // Check for failures in parallel steps
    if (shouldAbortWorkflow(analyzeResult)) {
      throw new Error(`Failure in analyze package step: ${analyzeResult.error || 'Package analysis failed'}`);
    }

    if (shouldAbortWorkflow(discoverResult)) {
      throw new Error(`Failure in discover units step: ${discoverResult.error || 'Unit discovery failed'}`);
    }

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Read the underlying cloneResult.error appended to this message and fix that root cause (bad URL, auth, network)
  2. Verify the template repository URL and requested ref (branch/tag/commit) exist and are reachable with git clone <url> manually
  3. Ensure credentials are available (SSH key, GITHUB_TOKEN/PAT) for private templates
  4. Check the destination directory: free disk space, write permissions, and that the path is not already occupied
  5. Retry on transient network failures
Defensive patterns

Strategy: retry

Validate before calling

const { execSync } = require('node:child_process');
export function assertRepoClonable(url: string, ref?: string) {
  execSync(`git ls-remote ${JSON.stringify(url)}${ref ? ' ' + ref : ''}`, { stdio: 'ignore' });
}
// call before starting the workflow; throws if URL/ref is unreachable or unauthorized

Type guard

export function cloneSucceeded(r: { templateDir?: string; error?: string }) {
  return typeof r?.templateDir === 'string' && r.templateDir.length > 0 && !r.error;
}

Try / catch

try {
  await run.start({ repoUrl, ref, ... });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Critical failure in clone step:')) {
    const cause = e.message.replace('Critical failure in clone step: ', '');
    // inspect cause: auth vs network vs bad ref, then retry with backoff
  }
  throw e;
}

Prevention

When it happens

Trigger: cloneTemplateStep returns a failure result — typically the git clone of the template repository failed: unreachable/incorrect repo URL, missing or expired credentials for a private repo, nonexistent branch/tag/commit, or no write access to the destination directory.

Common situations: Private template repos without a token in the environment, typos in the template slug/repo URL, corporate proxies blocking git over HTTPS, SSH keys not configured, or the destination path already existing and being non-empty.

Related errors

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