Cannot adopt ${worktreePath}: .git pointer is not a git-work

Error message

Cannot adopt ${worktreePath}: .git pointer is not a git-worktree reference.

What it means

verifyWorktreeOwnership refuses to adopt a directory whose .git pointer does not identify it as a git linked worktree (worktreeIdentity.linkedWorktree is falsy). This covers submodule .git pointers, plain directories, or malformed pointers where ownership cannot be confirmed, so the safe behavior is to refuse adoption.

Source

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

  let worktreeIdentity: GitCheckoutIdentity;
  let expectedIdentity: GitCheckoutIdentity;
  try {
    [worktreeIdentity, expectedIdentity] = await Promise.all([
      getGitCheckoutIdentity(worktreePath),
      getGitCheckoutIdentity(expectedRepo),
    ]);
  } catch (error) {
    throw new Error(
      `Cannot verify worktree ownership at ${worktreePath}: ${(error as Error).message}`,
      {
        cause: error,
      }
    );
  }
  if (!worktreeIdentity.linkedWorktree) {
    // Not a git-worktree pointer (e.g., submodule pointer, or malformed).
    // We cannot confirm this is our worktree, so refuse adoption.
    throw new Error(`Cannot adopt ${worktreePath}: .git pointer is not a git-worktree reference.`);
  }

  // Compare resolved common-directory paths: the primary checkout and every
  // linked worktree share this Git identity, while separate clones differ.
  if (resolve(worktreeIdentity.commonGitDir) !== resolve(expectedIdentity.commonGitDir)) {
    throw new Error(
      `Worktree at ${worktreePath} belongs to a different clone (${worktreeIdentity.commonGitDir}). ` +
        'Remove it from that clone or use a different codebase registration.'
    );
  }
}

View on GitHub (pinned to 0773b97458)

Solutions

Delete or move the non-worktree directory and create a proper one with `git worktree add <path> <branch>`.
If the directory is a separate clone you want to use, register that clone as its own codebase instead of adopting it as a worktree.
Inspect the .git entry: it must be a file containing `gitdir: <repo>/.git/worktrees/<name>` for adoption to succeed.
If it was a submodule checkout, initialize it through its parent repo rather than treating it as a worktree.

Example fix

// before: independent clone at the worktree path
git clone /srv/clone /srv/app  # .git is a directory, not a worktree pointer
// after: proper linked worktree
rm -rf /srv/app && cd /srv/clone && git worktree add /srv/app feat-branch

Defensive patterns

Strategy: validation

Validate before calling

import { statSync, readFileSync } from 'node:fs';
function isLinkedWorktreePointer(p: string): boolean {
  const dotGit = `${p}/.git`;
  try {
    return statSync(dotGit).isFile() && readFileSync(dotGit, 'utf8').startsWith('gitdir:');
  } catch { return false; }
}
if (!isLinkedWorktreePointer(worktreePath)) {
  throw new Error(`${worktreePath} is not a linked worktree; recreate with git worktree add`);
}

Type guard

function isLinkedWorktree(p: string): boolean {
  const dotGit = `${p}/.git`;
  try { return statSync(dotGit).isFile(); } catch { return false; }
}

Try / catch

try {
  await assertWorktreeOwnership(worktreePath, expectedRepo);
} catch (e) {
  if (e.message.includes('not a git-worktree reference')) {
    console.error('Directory is a clone/submodule, not a worktree; recreate it');
  } else throw e;
}

Prevention

Never `git clone` into a path reserved for a worktree.
Initialize submodules outside worktree-reserved directories.
Check the .git entry is a `gitdir:` file before reusing an existing directory.

When it happens

Trigger: Calling findExisting/assertWorktreeOwnership on a path that contains a .git directory (a full independent clone) or a submodule-style .git file instead of a `gitdir: ...` worktree pointer, so getGitCheckoutIdentity returns no linkedWorktree.

Common situations: Someone ran `git clone` into the worktree path separately; a directory created by cloning rather than `git worktree add`; a submodule checkout sitting where the worktree is expected; hand-crafted or truncated .git files.

Related errors

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