Couldn't find the git superproject root directory Failure wh

Error message

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

What it means

Thrown by getGitSuperProjectRoot when `git rev-parse --show-superproject-working-tree` runs but returns a non-zero exit code. Note: this command legitimately returns non-zero in a non-submodule repo; Docusaurus treats any non-zero as fatal here, so the practical trigger is a git state where the probe exits non-zero unexpectedly (e.g. inside a broken submodule, detached gitdir, or git older than the flag).

Source

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

  };

  const result = await execa(
    'git',
    ['rev-parse', '--show-superproject-working-tree'],
    {
      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,
      )}`,
    );
  }

  const output = result.stdout.trim();
  // this command only works when inside submodules
  // otherwise it doesn't return anything when we are inside the main repo
  if (output) {
    return fs.realpath.native(output);
  }
  return getGitRepoRoot(cwd);
}

// See https://git-scm.com/book/en/v2/Git-Tools-Submodules
export async function getGitSubmodulePaths(cwd: string): Promise<string[]> {

View on GitHub (pinned to 3f483e80e3)

Solutions

Upgrade git to >= 2.13 (flag was added in 2.13).
Re-initialize submodules: `git submodule update --init --recursive`.
Run from the main repo root instead of inside a submodule if submodule info is not needed.
Repair or remove the broken worktree.

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  const roots = await getGitAllRepoRoots(cwd);
} catch (e) {
  const cause = (e as Error).cause as Error;
  if (/show-superproject-working-tree/.test(cause?.message ?? '')) {
    // upgrade git or repair submodule/worktree state
  }
}

Prevention

Use git >= 2.13 in all environments.
Keep submodules fully initialized (`git submodule update --init`).
Avoid running submodule-aware builds from inside broken worktrees.

When it happens

Trigger: Running getGitAllRepoRoots inside a submodule whose gitdir is broken, with a git version predating --show-superproject-working-tree (git < 2.13), or in a repo where the worktree is corrupted.

Common situations: Old git in CI images, partially-initialized submodules (`git submodule update` not run), or a worktree created with `git worktree add` whose links were later removed.

Related errors

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