vercel/turborepo · error · Error

`git ` failed

Error message

`git ${args[0]}` failed:
${formatError(error)}

What it means

Thrown by runGit in @turbo-utils/examples.ts when an execFileSync('git', ...) invocation exits non-zero; downloadAndExtractExample uses a partial clone (no blobs, no checkout) then sparse-checkout to extract one example. The message names the failing git subcommand and includes stderr captured from the process, so the underlying git error is visible.

Solutions

1. Read the stderr embedded in the message; it is git's own error output and pinpoints the cause
2. Confirm git is installed and on PATH: git --version (partial clone needs git >= 2.19, sparse-checkout >= 2.25)
3. If a proxy is required, configure git: git config --global http.proxy http://proxy:port
4. Verify network access to github.com from the environment
5. Ensure the destination root is writable so .turbo-clone-temp can be created

import { execFileSync } from "node:child_process";

function gitAvailable(): boolean {
  try {
    execFileSync("git", ["--version"], { stdio: "pipe" });
    return true;
  } catch {
    return false;
  }
}
// if (!gitAvailable()) throw new Error("git >= 2.25 is required (sparse checkout)");

try {
  await downloadAndExtractExample(root, name);
} catch (err) {
  const msg = String(err?.message);
  if (msg.includes("ENOSYS") || msg.includes("not found")) {
    throw new Error("git binary missing on PATH", { cause: err });
  }
  throw err; // message already embeds git's stderr - surface it to the user
}

When it happens

Trigger: git not installed or not on PATH (ENOENT surfaces as spawn failure), no network access to github.com for git clone --filter=blob:none, corporate proxies blocking the git smart-http protocol, old git versions that do not support --filter/sparse-checkout, or disk/permission errors writing .turbo-clone-temp.

Common situations: Minimal Docker/CI images without git installed, locked-down corporate networks, git < 2.25 (sparse-checkout) or < 2.19 (partial clone), read-only destination directories, or authentication prompts on a private repo.

Related errors

• Failed to download
• Git download failed: Falling back to downloading the…
• Directory path contains potentially unsafe characters
• Invalid : path must be an absolute, non-empty string…
• Invalid example name

AI-assisted analysis of vercel/turborepo@f9245100cf (2026-08-17). Data as JSON: /api/errors/ce3fb6a90815d744. Report an issue: GitHub.

Appendix: source

Thrown at packages/turbo-utils/src/examples.ts:517

function formatError(error: unknown): string {
  if (error && typeof error === "object" && "stderr" in error) {
    const { stderr } = error as { stderr?: unknown };
    if (typeof stderr === "string" || Buffer.isBuffer(stderr)) {
      const output = stderr.toString().trim();
      if (output) {
        return output;
      }
    }
  }

  return error instanceof Error ? error.message : String(error);
}

function runGit(args: Array<string>, cwd?: string): void {
  try {
    execFileSync("git", args, { cwd, stdio: "pipe" });
  } catch (error) {
    throw new Error(`\`git ${args[0]}\` failed:\n${formatError(error)}`);
  }
}

function cleanupCloneDirectory(tempDir: string): void {
  try {
    rmSync(tempDir, {
      recursive: true,
      force: true,
      maxRetries: 5,
      retryDelay: 100
    });
  } catch (error) {
    warn(
      `Unable to remove temporary directory ${tempDir}:\n${formatError(error)}`
    );
  }
}

View on GitHub (pinned to f9245100cf)