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 returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(result.stderr)}

What it means

The exitCode branch of getGitSubmodulePaths: `git submodule status` ran but exited non-zero. git uses non-zero here for corrupt submodule metadata, unreadable .gitmodules, or a partially-cloned superproject.

Source

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

    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) {
    return [];
  }

  /* The output may contain a space/-/+/U prefix, for example
     1234567e3e35d1f5b submodules/foo (heads/main)
    -9ab1f1d3a2d77b0a4 submodules/bar (heads/dev)
    +f00ba42e1b3ddead submodules/baz (remotes/origin/main)
    Udeadbeefcafe1234 submodules/qux

View on GitHub (pinned to 3f483e80e3)

Solutions

Initialize and update submodules: `git submodule update --init --recursive`.
Inspect .gitmodules for conflicts or stale entries and fix/remove them.
If submodules are intentionally absent, simplify by not enabling submodule-aware VCS collection.

Defensive patterns

Strategy: validation

Validate before calling

import {execSync} from 'child_process';
function submodulesHealthy(cwd: string): boolean {
  try {
    execSync('git submodule status', {cwd, stdio: 'ignore'});
    return true;
  } catch { return false; }
}

Try / catch

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

Prevention

Always run `git submodule update --init --recursive` after clone.
Resolve .gitmodules conflicts before building.
Remove stale submodule registrations from .gitmodules.

When it happens

Trigger: Superproject has a .gitmodules referencing a submodule that was never initialized/cloned, .gitmodules is corrupt, or submodule gitdirs are in a half-cloned state.

Common situations: CI checkout with `submodules: false` then a submodule-aware build; corrupt .gitmodules after a merge conflict; submodule removed from git but not from .gitmodules.

Related errors

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