{"record":{"id":"c240fa815f516589","repo":"mastra-ai/mastra","slug":"critical-failure-in-clone-step-cloneresult-erro","errorCode":null,"errorMessage":"Critical failure in clone step: ${cloneResult.error}","messagePattern":"Critical failure in clone step: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/agent-builder/src/workflows/template-builder/template-builder.ts","lineNumber":1609,"sourceCode":"  steps: [\n    cloneTemplateStep,\n    analyzePackageStep,\n    discoverUnitsStep,\n    orderUnitsStep,\n    packageMergeStep,\n    installStep,\n    programmaticFileCopyStep,\n    intelligentMergeStep,\n    validationAndFixStep,\n  ],\n})\n  .then(cloneTemplateStep)\n  .map(async ({ getStepResult }) => {\n    const cloneResult = getStepResult(cloneTemplateStep);\n\n    // Check for failure in clone step\n    if (shouldAbortWorkflow(cloneResult)) {\n      throw new Error(`Critical failure in clone step: ${cloneResult.error}`);\n    }\n\n    return cloneResult;\n  })\n  .parallel([analyzePackageStep, discoverUnitsStep])\n  .map(async ({ getStepResult }) => {\n    const analyzeResult = getStepResult(analyzePackageStep);\n    const discoverResult = getStepResult(discoverUnitsStep);\n\n    // Check for failures in parallel steps\n    if (shouldAbortWorkflow(analyzeResult)) {\n      throw new Error(`Failure in analyze package step: ${analyzeResult.error || 'Package analysis failed'}`);\n    }\n\n    if (shouldAbortWorkflow(discoverResult)) {\n      throw new Error(`Failure in discover units step: ${discoverResult.error || 'Unit discovery failed'}`);\n    }\n","sourceCodeStart":1591,"sourceCodeEnd":1627,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/agent-builder/src/workflows/template-builder/template-builder.ts#L1591-L1627","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the underlying cloneResult.error appended to this message and fix that root cause (bad URL, auth, network)","Verify the template repository URL and requested ref (branch/tag/commit) exist and are reachable with git clone <url> manually","Ensure credentials are available (SSH key, GITHUB_TOKEN/PAT) for private templates","Check the destination directory: free disk space, write permissions, and that the path is not already occupied","Retry on transient network failures"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const { execSync } = require('node:child_process');\nexport function assertRepoClonable(url: string, ref?: string) {\n  execSync(`git ls-remote ${JSON.stringify(url)}${ref ? ' ' + ref : ''}`, { stdio: 'ignore' });\n}\n// call before starting the workflow; throws if URL/ref is unreachable or unauthorized","typeGuard":"export function cloneSucceeded(r: { templateDir?: string; error?: string }) {\n  return typeof r?.templateDir === 'string' && r.templateDir.length > 0 && !r.error;\n}","tryCatchPattern":"try {\n  await run.start({ repoUrl, ref, ... });\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Critical failure in clone step:')) {\n    const cause = e.message.replace('Critical failure in clone step: ', '');\n    // inspect cause: auth vs network vs bad ref, then retry with backoff\n  }\n  throw e;\n}","preventionTips":["Validate the repo URL and ref with git ls-remote before starting the workflow","Configure credentials (PAT/SSH keys) in the environment for private templates","Pre-check destination path: exists, writable, sufficient disk space","Add bounded retries with backoff for transient network failures"],"tags":["git","clone","workflow","template-builder"],"backgroundTag":"git-clone-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}