This Docusaurus site is outside any Git worktree. Unable to

Error message

This Docusaurus site is outside any Git worktree.
Unable to read Git info for file ${logger.path(filePath)}

What it means

Thrown by the eager git VCS's getGitFileInfo when initialization reported reason 'not-in-worktree' — i.e. the build is running outside any git worktree, yet a component asked for git metadata (last update author/date) for a specific file. The trailing space in the message is intentional in source. This is the runtime consequence of error 101 happening during init.

Source

Thrown at packages/docusaurus-utils/src/vcs/vcsGitEager.ts:91

    if (!isInWorktree) {
      return {type: 'error', reason: 'not-in-worktree'};
    }
    const filesMap = await loadAllGitFilesInfoMap(siteDir);
    return {type: 'success', filesMap};
  } catch (error) {
    return {type: 'error', reason: 'unknown', cause: error as Error};
  }
}

export function createVcsGitEagerConfig(): VcsConfig {
  let initPromise: Promise<InitializeResult> | null = null;

  async function getGitFileInfo(filePath: string): Promise<GitFileInfo | null> {
    const init = (await initPromise)!;
    if (init.type === 'success') {
      return init.filesMap.get(filePath) ?? null;
    } else if (init.reason === 'not-in-worktree') {
      throw new Error(
        `This Docusaurus site is outside any Git worktree.
Unable to read Git info for file ${logger.path(filePath)} `,
      );
    } else {
      throw init.cause;
    }
  }

  return {
    initialize: ({siteDir}) => {
      if (initPromise) {
        // We only initialize this VCS once!
        // For i18n sites, this permits reading ahead of time for all locales
        // so that it only slows down the first locale
        // I assume this logic is fine, but we'll see if it causes trouble

        // Note: we could also only call "initialize()" once from the outside,
        // But maybe it could be useful for custom VCS implementations to be

View on GitHub (pinned to 3f483e80e3)

Solutions

Build from within the actual git checkout so the worktree is detected.
Disable git-backed last-update/author features, or switch to a non-git VCS preset that does not require a worktree.
Ensure CI clones the repo (`actions/checkout`) rather than copying files.

Defensive patterns

Strategy: validation

Validate before calling

import {execSync} from 'child_process';
function isInWorktree(cwd: string): boolean {
  try { execSync('git rev-parse --is-inside-work-tree', {cwd, stdio: 'ignore'}); return true; }
  catch { return false; }
}
// if false, do not enable git-backed last-update/author features

Try / catch

try {
  const info = await vcs.getGitFileInfo(filePath);
} catch (e) {
  if (/outside any Git worktree/.test(String(e))) return null; // degrade gracefully
  throw e;
}

Prevention

Build from the real git checkout, not an unpacked tarball.
In Docker, clone the repo inside the image rather than copying sources.
Disable last-update/author features when git metadata is unavailable.

When it happens

Trigger: Site is built outside a git checkout but theme code or plugins call getGitFileInfo for a markdown/asset file (e.g. to render 'last updated by').

Common situations: Unpacked release tarball with no `.git`, vendored docs, Docker image that copied sources without git metadata, or build triggered from /tmp.

Related errors

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