Could not get all the git repository root paths (superprojec

Error message

Could not get all the git repository root paths (superproject + submodules) from cwd=${cwd}

What it means

Top-level catch in getGitAllRepoRoots: any failure from getGitSuperProjectRoot or getGitSubmodulePaths (errors 102-106) is wrapped with a generic 'Could not get all the git repository root paths' message and the original error chained as cause. This is the user-facing aggregate; look at error.cause for the real reason.

Source

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

  return Promise.all(output.split('\n').map(getSubmodulePath));
}

// Find the root git repository alongside all its submodules, if any
export async function getGitAllRepoRoots(cwd: string): Promise<string[]> {
  try {
    const superProjectRoot = await getGitSuperProjectRoot(cwd);
    if (!superProjectRoot) {
      return [];
    }
    let submodulePaths = await getGitSubmodulePaths(superProjectRoot);
    submodulePaths = await Promise.all(
      submodulePaths.map((submodulePath) =>
        fs.realpath.native(path.resolve(superProjectRoot, submodulePath)),
      ),
    );
    return [superProjectRoot, ...submodulePaths];
  } catch (error) {
    throw new Error(
      `Could not get all the git repository root paths (superproject + submodules) from cwd=${cwd}`,
      {cause: error},
    );
  }
}

// Useful information about a file tracked in a Git repository
export type GitFileInfo = {
  creation: GitCommitInfo;
  lastUpdate: GitCommitInfo;
};

// A map of all the files tracked in a Git repository
export type GitFileInfoMap = Map<string, GitFileInfo>;

// Logic inspired from Astro Starlight:
// See https://bsky.app/profile/bluwy.me/post/3lyihod6qos2a
// See https://github.com/withastro/starlight/blob/c417f1efd463be63b7230617d72b120caed098cd/packages/starlight/utils/git.ts#L58

View on GitHub (pinned to 3f483e80e3)

Solutions

Inspect error.cause to identify which underlying failure (102-106) actually fired, then apply that error's fix.
Repair the git worktree state (submodules init, valid cwd, git on PATH).
Re-run from a clean checkout of the superproject.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const roots = await getGitAllRepoRoots(cwd);
} catch (e) {
  const cause = (e as Error).cause as Error | undefined;
  // dispatch on cause.message to handle 102-106 specifically
  logVcsInitFailure(cause ?? e);
}

Prevention

Always inspect error.cause for the real underlying git failure.
Keep the whole worktree (superproject + submodules) healthy before building.
Run a preflight: `git rev-parse`, `git submodule status` from the build cwd.

When it happens

Trigger: Any of errors 102-106 firing during enumeration of superproject + submodule roots.

Common situations: Broken submodule state, missing git, deleted cwd, or a corrupted worktree surfaced during VCS initialization.

Related errors

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