{"record":{"id":"31dd166634c18067","repo":"facebook/docusaurus","slug":"couldn-t-read-the-list-of-git-submodules-failure-w-31dd16","errorCode":null,"errorMessage":"Couldn't read the list of git submodules\nFailure while running ${logger.code('git submodule status')} from cwd=${logger.path(cwd)}\nThe command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(result.stderr)}","messagePattern":"Couldn't read the list of git submodules\nFailure while running (.+?) from cwd=(.+?)\nThe command returned exit code (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils/src/vcs/gitUtils.ts","lineNumber":376,"sourceCode":"    return `Couldn't read the list of git submodules\nFailure while running ${logger.code(\n      'git submodule status',\n    )} from cwd=${logger.path(cwd)}`;\n  };\n\n  const result = await execa('git', ['submodule', 'status'], {\n    cwd,\n  }).catch((error) => {\n    // We enter this rejection when cwd is not a dir for example\n    throw new Error(\n      `${createErrorMessageBase()}\nThe command executed throws an error: ${error.message}`,\n      {cause: error},\n    );\n  });\n\n  if (result.exitCode !== 0) {\n    throw new Error(\n      `${createErrorMessageBase()}\nThe command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(\n        result.stderr,\n      )}`,\n    );\n  }\n\n  const output = result.stdout.trim();\n\n  if (!output) {\n    return [];\n  }\n\n  /* The output may contain a space/-/+/U prefix, for example\n     1234567e3e35d1f5b submodules/foo (heads/main)\n    -9ab1f1d3a2d77b0a4 submodules/bar (heads/dev)\n    +f00ba42e1b3ddead submodules/baz (remotes/origin/main)\n    Udeadbeefcafe1234 submodules/qux","sourceCodeStart":358,"sourceCodeEnd":394,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils/src/vcs/gitUtils.ts#L358-L394","documentation":"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.","triggerScenarios":"Superproject has a .gitmodules referencing a submodule that was never initialized/cloned, .gitmodules is corrupt, or submodule gitdirs are in a half-cloned state.","commonSituations":"CI checkout with `submodules: false` then a submodule-aware build; corrupt .gitmodules after a merge conflict; submodule removed from git but not from .gitmodules.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import {execSync} from 'child_process';\nfunction submodulesHealthy(cwd: string): boolean {\n  try {\n    execSync('git submodule status', {cwd, stdio: 'ignore'});\n    return true;\n  } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await getGitSubmodulePaths(root);\n} catch (e) {\n  if (/git submodule status/.test(String(e))) repairSubmodules(root);\n  else throw e;\n}","preventionTips":["Always run `git submodule update --init --recursive` after clone.","Resolve .gitmodules conflicts before building.","Remove stale submodule registrations from .gitmodules."],"tags":["git","vcs","submodule","config"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}