What causes "Failed to parse git submodule line: ${line}" in facebook/docusaurus?

Run `git submodule status` manually and inspect each line for missing/odd path tokens.

Failed to parse git submodule line: ${line}

Error message

Failed to parse git submodule line: ${line}

What it means

Thrown by the getSubmodulePath parser inside getGitSubmodulePaths when a line from `git submodule status` does not match the expected `<prefix><sha> <path> (<branch>)` shape — specifically when `line.substring(1).split(' ')[1]` is falsy. This means git emitted a status line without a path token, which the parser cannot handle.

Source

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

    );
  }

  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
   */
  const getSubmodulePath = async (line: string) => {
    const submodulePath = line.substring(1).split(' ')[1];
    if (!submodulePath) {
      throw new Error(`Failed to parse git submodule line: ${line}`);
    }
    return submodulePath;
  };

  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)),

View on GitHub (pinned to 3f483e80e3)

Solutions

Run `git submodule status` manually and inspect each line for missing/odd path tokens.
Fix the offending entry in .gitmodules and re-register the submodule.
Remove and re-add the problematic submodule if its state is unrecoverable.
Report the offending line upstream if it appears well-formed — the parser may need broadening.

Defensive patterns

Strategy: validation

Validate before calling

function isValidSubmoduleLine(line: string): boolean {
  // expected: <prefix><sha> <path> (<branch>)
  const token = line.substring(1).split(' ')[1];
  return Boolean(token);
}

Type guard

function isParsableSubmoduleLine(line: string): line is string {
  return Boolean(line.substring(1).split(' ')[1]);
}

Prevention

Inspect `git submodule status` output before relying on it.
Avoid submodule paths with leading spaces or unusual formatting.
Keep .gitmodules entries well-formed.

When it happens

Trigger: A submodule path containing unusual formatting, a status line that is just a prefix+sha with no path, or a git version that emits a differently-formatted status line. Also reachable if a submodule path is empty in .gitmodules.

Common situations: Exotic submodule paths (leading spaces, unusual characters), corrupted submodule registration, or a git version producing non-standard output.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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