coleam00/Archon · error · Error

Failed to check worktree at ${worktreePath}: ${err.message}

Error message

Failed to check worktree at ${worktreePath}: ${err.message}

What it means

Thrown by worktreeExists in packages/git/src/worktree.ts when the filesystem probe of a worktree path fails with an unexpected error. ENOENT on the .git file is treated as a corruption signal (returns false), but any other fs error (permissions, EACCES, EIO, symlink loops) surfaces as this wrapper error preserving the original message.

Source

Thrown at packages/git/src/worktree.ts:176

    }
    getLog().error({ worktreePath, err, code: err.code }, 'worktree.existence_check_failed');
    throw new Error(`Failed to check worktree at ${worktreePath}: ${err.message}`);
  }

  // Step 2: Check if .git entry exists (directory exists at this point)
  try {
    const gitPath = join(worktreePath, '.git');
    await access(gitPath);
    return true;
  } catch (error) {
    const err = error as NodeJS.ErrnoException;
    if (err.code === 'ENOENT') {
      // Directory exists but .git is missing — corruption signal
      getLog().warn({ worktreePath }, 'worktree.corruption_detected');
      return false;
    }
    getLog().error({ worktreePath, err, code: err.code }, 'worktree.existence_check_failed');
    throw new Error(`Failed to check worktree at ${worktreePath}: ${err.message}`);
  }
}

/**
 * List all worktrees for a repository
 * Returns array of {path, branch} objects parsed from git worktree list --porcelain
 *
 * Only returns [] for expected "not a git repository" errors.
 * Throws for unexpected errors (permission denied, git not found, etc.)
 */
export async function listWorktrees(repoPath: RepoPath): Promise<WorktreeInfo[]> {
  try {
    const { stdout } = await execFileAsync(
      'git',
      ['-C', repoPath, 'worktree', 'list', '--porcelain'],
      { timeout: 10000 }
    );

View on GitHub (pinned to 0773b97458)

Solutions

Check permissions on the worktree path and all parents: ls -la on each component; fix ownership or run as a user with access
If the path is a broken symlink or odd mount, remove or repair it, then re-create the worktree with git worktree add
On network/ephemeral filesystems, move worktrees to local disk
Catch this error at the call site and treat it as 'state unknown' — do not assume the worktree exists or not

Example fix

// before
const ok = await worktreeExists(path); // throws on EACCES
// after
let ok: boolean;
try {
  ok = await worktreeExists(path);
} catch (e) {
  getLog().warn({ path, err: e }, 'worktree state unknown, treating as missing');
  ok = false;
}

Defensive patterns

Strategy: try-catch

Validate before calling

import { accessSync, constants } from 'node:fs';
try {
  accessSync(worktreePath, constants.R_OK);
} catch (e) {
  console.warn(`Worktree path not accessible: ${(e as NodeJS.ErrnoException).code}`);
}

Type guard

function isWorktreeCheckFailure(e: unknown): boolean {
  return e instanceof Error && e.message.startsWith('Failed to check worktree at ');
}

Try / catch

try {
  const exists = await worktreeExists(path);
} catch (e) {
  if (isWorktreeCheckFailure(e)) {
    getLog().warn({ path, err: e }, 'existence unknown; assuming missing and re-creating');
    return false;
  }
  throw e;
}

Prevention

Run all processes touching worktrees as the same user to avoid EACCES
Keep worktrees on local disk, not NFS or container mounts that can return EIO
Avoid broken symlinks in worktree parent paths
Pre-check path readability in setup scripts before adopting worktrees

When it happens

Trigger: Calling worktreeExists (directly or via exists/get/adopt/healthCheck/findExisting) when the stat/read of worktreePath or its .git file throws something other than ENOENT.

Common situations: Parent directory with restrictive permissions (EACCES) after a uid change or running in a container as another user; a path that is a broken symlink causing ELOOP; NFS/network filesystem returning EIO; stale mounts in CI containers.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/4f2a5ec8a9296e19. Report an issue: GitHub.