bmad-code-org/BMAD-METHOD · error · Error

Failed to clone ${parsed.cloneUrl}${refSuffix}: ${error_.mes

Error message

Failed to clone ${parsed.cloneUrl}${refSuffix}: ${error_.message}

What it means

Thrown by cloneRepo() inside the git clone catch block when execSync('git clone ...') fails for a remote URL. The error message includes the clone URL, optional @version suffix, and the underlying git error message. This is the primary network/repository-access failure path for custom module cloning.

Source

Thrown at tools/installer/modules/custom-module-manager.js:496

      const fetchSpinner = await createSpinner();
      fetchSpinner.start(`Cloning ${displayName}${effectiveVersion ? ` @ ${effectiveVersion}` : ''}...`);
      try {
        if (effectiveVersion) {
          execSync(`git clone --depth 1 --branch ${quoteCustomRef(effectiveVersion)} "${parsed.cloneUrl}" "${repoCacheDir}"`, {
            stdio: ['ignore', 'pipe', 'pipe'],
            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
          });
        } else {
          execSync(`git clone --depth 1 "${parsed.cloneUrl}" "${repoCacheDir}"`, {
            stdio: ['ignore', 'pipe', 'pipe'],
            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
          });
        }
        fetchSpinner.stop(`Cloned ${displayName}`);
      } catch (error_) {
        fetchSpinner.error(`Failed to clone ${displayName}`);
        const refSuffix = effectiveVersion ? `@${effectiveVersion}` : '';
        throw new Error(`Failed to clone ${parsed.cloneUrl}${refSuffix}: ${error_.message}`);
      }
    }

    // Record the resolved SHA for the manifest writer.
    let resolvedSha = null;
    try {
      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
    } catch {
      // swallow — a non-git repo (local path) wouldn't reach here anyway
    }
    // Best-effort: capture the remote default branch name so channel marker
    // metadata for "next" reflects the actual tracked ref (not always "main").
    let defaultRef = 'main';
    if (!effectiveVersion) {
      try {
        const symbolic = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
          cwd: repoCacheDir,
          stdio: 'pipe',

View on GitHub (pinned to b70486b9bd)

Solutions

1. Verify the repository URL is correct and accessible (try git clone manually).
2. If using SSH, ensure your SSH key is added and the host is in known_hosts.
3. If using HTTPS to a private repo, configure credentials (credential helper or token in the URL).
4. Verify the branch/tag name in the @version suffix exists on the remote.
5. Check network connectivity and proxy settings.

Example fix

// before
await mgr.cloneRepo('https://github.com/org/wrong-repo.git@nonexistent-tag');

// after — verify URL and tag manually first
// $ git ls-remote --tags https://github.com/org/repo.git
await mgr.cloneRepo('https://github.com/org/repo.git@v1.2.3');

// Pre-flight check: verify the URL is reachable
const { execSync } = require('child_process');

function canReachRepo(url) {
  try {
    execSync(`git ls-remote --exit-code "${url}" HEAD`, { stdio: 'ignore', timeout: 15000 });
    return true;
  } catch {
    return false;
  }
}

if (!canReachRepo(url)) {
  throw new Error('Repository is not reachable. Check the URL, network, and credentials.');
}

const MAX_RETRIES = 3;
for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
  try {
    await mgr.cloneRepo(url, options);
    break;
  } catch (e) {
    if (e.message.startsWith('Failed to clone') && attempt < MAX_RETRIES) {
      console.log(`Clone attempt ${attempt} failed, retrying...`);
      await new Promise(r => setTimeout(r, 2000 * attempt));
      continue;
    }
    throw e;
  }
}

When it happens

Trigger: The repository URL is wrong or doesn't exist; network is down; the branch/tag specified via @version or pinOverride doesn't exist on the remote; authentication is required but GIT_TERMINAL_PROMPT is set to 0; a firewall blocks the connection; the git binary is not installed.

Common situations: Private repo without credentials configured; typo in the repo URL; the requested tag was deleted; SSH key not set up for git@ URLs; corporate proxy blocks HTTPS git; git not on PATH.

Related errors

• Failed to clone external module '${moduleCode}' at ${resolve
• Subdirectory '${parsed.subdir}' not found in cloned reposito
• Could not resolve stable tag for '${moduleCode}' (${error.me
• Unexpected response from ${url}
• Unsafe ref name: ${JSON.stringify(ref)}

AI-assisted analysis of bmad-code-org/BMAD-METHOD@b70486b9bd (2026-08-13). Data as JSON: /api/errors/c7781372d8711ff1. Report an issue: GitHub.