{"record":{"id":"4f2a5ec8a9296e19","repo":"coleam00/Archon","slug":"failed-to-check-worktree-at-worktreepath-err","errorCode":null,"errorMessage":"Failed to check worktree at ${worktreePath}: ${err.message}","messagePattern":"Failed to check worktree at (.+?): (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/git/src/worktree.ts","lineNumber":176,"sourceCode":"    }\n    getLog().error({ worktreePath, err, code: err.code }, 'worktree.existence_check_failed');\n    throw new Error(`Failed to check worktree at ${worktreePath}: ${err.message}`);\n  }\n\n  // Step 2: Check if .git entry exists (directory exists at this point)\n  try {\n    const gitPath = join(worktreePath, '.git');\n    await access(gitPath);\n    return true;\n  } catch (error) {\n    const err = error as NodeJS.ErrnoException;\n    if (err.code === 'ENOENT') {\n      // Directory exists but .git is missing — corruption signal\n      getLog().warn({ worktreePath }, 'worktree.corruption_detected');\n      return false;\n    }\n    getLog().error({ worktreePath, err, code: err.code }, 'worktree.existence_check_failed');\n    throw new Error(`Failed to check worktree at ${worktreePath}: ${err.message}`);\n  }\n}\n\n/**\n * List all worktrees for a repository\n * Returns array of {path, branch} objects parsed from git worktree list --porcelain\n *\n * Only returns [] for expected \"not a git repository\" errors.\n * Throws for unexpected errors (permission denied, git not found, etc.)\n */\nexport async function listWorktrees(repoPath: RepoPath): Promise<WorktreeInfo[]> {\n  try {\n    const { stdout } = await execFileAsync(\n      'git',\n      ['-C', repoPath, 'worktree', 'list', '--porcelain'],\n      { timeout: 10000 }\n    );\n","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/git/src/worktree.ts#L158-L194","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst ok = await worktreeExists(path); // throws on EACCES\n// after\nlet ok: boolean;\ntry {\n  ok = await worktreeExists(path);\n} catch (e) {\n  getLog().warn({ path, err: e }, 'worktree state unknown, treating as missing');\n  ok = false;\n}","handlingStrategy":"try-catch","validationCode":"import { accessSync, constants } from 'node:fs';\ntry {\n  accessSync(worktreePath, constants.R_OK);\n} catch (e) {\n  console.warn(`Worktree path not accessible: ${(e as NodeJS.ErrnoException).code}`);\n}","typeGuard":"function isWorktreeCheckFailure(e: unknown): boolean {\n  return e instanceof Error && e.message.startsWith('Failed to check worktree at ');\n}","tryCatchPattern":"try {\n  const exists = await worktreeExists(path);\n} catch (e) {\n  if (isWorktreeCheckFailure(e)) {\n    getLog().warn({ path, err: e }, 'existence unknown; assuming missing and re-creating');\n    return false;\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["filesystem","worktree","permissions"],"backgroundTag":"worktree-check-failed","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}