Couldn't read the list of git submodules Failure while runni

Error message

Couldn't read the list of git submodules
Failure while running ${logger.code('git submodule status')} from cwd=${logger.path(cwd)}
The command executed throws an error: ${error.message}

What it means

The spawn-rejection branch of getGitSubmodulePaths: `git submodule status` could not be launched or rejected (cwd invalid, git missing, EPERM). Cause is chained. Called from getGitAllRepoRoots after a superproject root was already located.

Source

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

    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[]> {
  const createErrorMessageBase = () => {
    return `Couldn't read the list of git submodules
Failure while running ${logger.code(
      'git submodule status',
    )} from cwd=${logger.path(cwd)}`;
  };

  const result = await execa('git', ['submodule', 'status'], {
    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();

  if (!output) {

View on GitHub (pinned to 3f483e80e3)

Solutions

Confirm superProjectRoot still exists at call time.
Ensure git stays available on PATH for the whole build.
Re-run from a stable checkout.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await getGitSubmodulePaths(root);
} catch (e) {
  if (/git submodule status/.test(String(e))) handleSpawnFailure(e);
  else throw e;
}

Prevention

Keep cwd valid for the whole build (do not delete it mid-run).
Lock git onto PATH for the entire build pipeline.
Avoid concurrent operations that remove the repo dir.

When it happens

Trigger: getGitSubmodulePaths(superProjectRoot) invoked with an invalid/deleted path, or git binary removed between the rev-parse and submodule calls.

Common situations: Race where the repo dir is removed mid-build, restricted CI sandbox that revokes git after the first call, or PATH manipulation between steps.

Related errors

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