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 executed throws an error: ${error.message}

What it means

Sibling of error 100 for getGitSuperProjectRoot: the execa call for `git rev-parse --show-superproject-working-tree` rejects before returning (invalid cwd, git missing, spawn failure). The cause is chained. This helper is only meaningfully called when submodules may be present.

Source

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

export async function getGitSuperProjectRoot(
  cwd: string,
): Promise<string | null> {
  const createErrorMessageBase = () => {
    return `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)}`;
  };

  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

View on GitHub (pinned to 3f483e80e3)

Solutions

Confirm `git rev-parse --show-superproject-working-tree` can be spawned at all (git installed, cwd valid).
Ensure Docusaurus is launched from an existing directory.
If submodules are irrelevant, ensure getGitAllRepoRoots is not invoked from a broken context.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await getGitAllRepoRoots(cwd);
} catch (e) {
  const cause = (e as Error).cause as Error | undefined;
  if (cause && /show-superproject-working-tree/.test(cause.message)) {
    // superproject probe failed at spawn — check git/cwd
  }
}

Prevention

Keep git available on PATH for the entire build.
Validate cwd liveness before invoking submodule-aware code.
Isolate the superproject probe so a failure can degrade gracefully.

When it happens

Trigger: getGitAllRepoRoots(cwd) running while cwd is invalid or git cannot be spawned; the superproject probe fails at the process level.

Common situations: Container/CI images without git, deleted cwd, or running a submodule-aware build in an environment where the git binary is sandboxed away.

Related errors

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