Couldn't check if this directory is within a Git worktree: $

Error message

Couldn't check if this directory is within a Git worktree: ${cwd}

What it means

Thrown by isGitInsideWorktree() when the underlying execa('git', ['rev-parse', '--is-inside-work-tree']) call itself rejects (note: reject:false is set, so a normal non-zero exit is captured and returns false; this catch is only entered when execa cannot spawn the process at all). The cause is the original spawn error. The function's purpose is to detect whether cwd is inside a git worktree, so a failure to even run git is wrapped with the offending cwd.

Source

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

): Promise<GitCommitInfo | null> {
  return getGitCommitInfo(filePath, 'newest');
}

export async function getGitCreation(
  filePath: string,
): Promise<GitCommitInfo | null> {
  return getGitCommitInfo(filePath, 'oldest');
}

export async function isGitInsideWorktree(cwd: string): Promise<boolean> {
  try {
    const result = await execa('git', ['rev-parse', '--is-inside-work-tree'], {
      cwd,
      reject: false,
    });
    return result.exitCode === 0;
  } catch (error) {
    throw new Error(
      `Couldn't check if this directory is within a Git worktree: ${cwd}`,
      {cause: error},
    );
  }
}

export async function getGitRepoRoot(cwd: string): Promise<string> {
  const createErrorMessageBase = () => {
    return `Couldn't find the git repository root directory
Failure while running ${logger.code(
      'git rev-parse --show-toplevel',
    )} from cwd=${logger.path(cwd)}`;
  };

  const result = await execa('git', ['rev-parse', '--show-toplevel'], {
    cwd,
  }).catch((error) => {
    // We enter this rejection when cwd is not a dir for example

View on GitHub (pinned to 3f483e80e3)

Solutions

Install git and verify `git --version` works (see error 93 fixes).
Confirm the cwd passed to isGitInsideWorktree exists, is a directory, and the current process can enter it.
If the call site cannot guarantee a usable cwd, guard with fs.pathExists(cwd) and skip the check when the directory is invalid.
Wrap the call in try/catch and treat the failure as 'not in a worktree' if that is a safe degradation for your use case.

Example fix

// before
const inside = await isGitInsideWorktree(cwd);

// after — guard cwd and tolerate spawn failures
if (!(await fs.pathExists(cwd))) return false;
let inside = false;
try {
  inside = await isGitInsideWorktree(cwd);
} catch (err) {
  console.warn(`Could not determine git worktree status for ${cwd}: ${err.cause ?? err}`);
}
return inside;

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs-extra';
import { execaSync } from 'execa';

function gitBinaryAvailable(): boolean {
  try { execaSync('git', ['--version']); return true; } catch { return false; }
}

async function canCheckWorktree(cwd: string): Promise<boolean> {
  return gitBinaryAvailable() && (await fs.stat(cwd)).isDirectory();
}

if (!(await canCheckWorktree(cwd))) {
  throw new Error(`Cannot check git worktree: git missing or cwd invalid: ${cwd}`);
}

Try / catch

try {
  await isGitInsideWorktree(cwd);
} catch (err) {
  if (err instanceof Error && err.message.startsWith("Couldn't check if this directory is within a Git worktree")) {
    // err.cause is the spawn error (often ENOENT — git not installed, or cwd invalid)
    // treat as 'not in a worktree' if that is a safe degradation
  }
  throw err;
}

Prevention

Install git in every environment that runs the build.
Validate the cwd argument (exists and is a directory) before calling isGitInsideWorktree.
When the check is non-critical, wrap it in try/catch and default to false on spawn failure.

When it happens

Trigger: Calling isGitInsideWorktree(cwd) in an environment where git is not installed (spawn ENOENT), or where cwd does not exist / is not a directory / cannot be entered, causing execa to throw before producing a result. Because reject:false only converts non-zero git exits into return values, only spawn-level failures reach this catch.

Common situations: git is not installed (same root cause as error 93 but surfaced from a different code path). The cwd argument points at a deleted or inaccessible directory. Running in a constrained sandbox that blocks process spawning. Permissions prevent entering the directory passed as cwd.

Related errors

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