Couldn't find the git repository root directory Failure whil

Error message

Couldn't find the git repository root directory
Failure while running ${logger.code('git rev-parse --show-toplevel')} from cwd=${logger.path(cwd)}
The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(result.stderr)}

What it means

Thrown by getGitRepoRoot when `git rev-parse --show-toplevel` runs successfully but returns a non-zero exit code, which is git's signal that cwd is not inside any git worktree. This is distinct from error 100 (spawn/rejection) and fires only when git itself ran and decided there is no enclosing repo.

Source

Thrown at packages/docusaurus-utils/src/vcs/gitUtils.ts:298

    return `Couldn't find the git repository root directory
Failure while running ${logger.code(
      'git rev-parse --show-toplevel',
    )} from cwd=${logger.path(cwd)}`;
  };

  const result = await execa('git', ['rev-parse', '--show-toplevel'], {
    cwd,
  }).catch((error) => {
    // We enter this rejection when cwd is not a dir for example
    throw new Error(
      `${createErrorMessageBase()}
The command executed throws an error: ${error.message}`,
      {cause: error},
    );
  });

  if (result.exitCode !== 0) {
    throw new Error(
      `${createErrorMessageBase()}
The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
        result.stderr,
      )}`,
    );
  }

  return fs.realpath.native(result.stdout.trim());
}

// A Git "superproject" is a Git repository that contains submodules
// See https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---show-superproject-working-tree
// See https://git-scm.com/book/en/v2/Git-Tools-Submodules
export async function getGitSuperProjectRoot(
  cwd: string,
): Promise<string | null> {
  const createErrorMessageBase = () => {
    return `Couldn't find the git superproject root directory

View on GitHub (pinned to 3f483e80e3)

Solutions

Move/clone the site into a real git checkout and re-run from there.
If git info is unwanted, set the VCS preset to a non-git provider via DOCUSAURUS_VCS.
Repair the repo: `git rev-parse --show-toplevel` must succeed from your cwd before invoking Docusaurus.
In CI, ensure `actions/checkout` (or equivalent) ran before the build step.

Example fix

// before
// running `docusaurus build` in /tmp/site with no .git
// after
git clone https://github.com/org/site && cd site && docusaurus build

Defensive patterns

Strategy: validation

Validate before calling

import {execSync} from 'child_process';
function isInGitWorktree(cwd: string): boolean {
  try {
    execSync('git rev-parse --show-toplevel', {cwd, stdio: 'ignore'});
    return true;
  } catch { return false; }
}

Try / catch

try {
  const root = await getGitRepoRoot(cwd);
} catch (e) {
  if (/Couldn't find the git repository root/.test(String(e))) {
    // not in a repo — disable git-backed VCS or clone first
  } else throw e;
}

Prevention

Always launch the build from inside the cloned checkout.
In CI, use actions/checkout before the build step.
For tarball-distributed sites, set a non-git VCS preset.

When it happens

Trigger: Calling getGitRepoRoot from a path that is not inside any git repository (no `.git` upward), or inside a worktree whose `.git` pointer is broken. Transitively hit whenever Docusaurus's eager git VCS initializes on a non-repo directory.

Common situations: Building Docusaurus from a freshly unpacked tarball/zip with no `.git`, running `docusaurus build` in `/tmp`, vendoring the site source without the git history, or a corrupted `.git` after a botched clone.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/3ded09747413d4d9. Report an issue: GitHub.