paperclipai/paperclip · error · WorkspaceValidationFailure

git_worktree_branch_mismatch

git_worktree_branch_mismatch

Error message

Issue ${issue.identifier ?? issue.id} expected git worktree branch "${expectedManagedBranchName}" at "${effectiveCwd}", but ${inspection.reason ?? "the checked-out branch could not be verified"}.

What it means

Error "Issue ${issue.identifier ?? issue.id} expected git worktree branch "${expectedManagedBranchName}" at "${effectiveCwd}", but ${inspection.reason ?? "the checked-out branch could not be verified"}." thrown in paperclipai/paperclip.

Source

Thrown at server/src/services/heartbeat.ts:2302

      scrubGitCredentialText(
        `Failed to prepare managed checkout for "${input.repoUrl}" at "${cwd}": ${reason}${authNote ? ` ${authNote}` : ""}`,
      ),
    );
  }

  try {
    await fs.rename(cloneTmpDir, cwd);
  } catch (renameError) {
    await fs
      .rm(cloneTmpDir, { recursive: true, force: true })
      .catch(() => undefined);
    // The target appearing between the emptiness check and the rename means another
    // materialization won the race; adopt its checkout instead of failing the run.
    if (await hasAdoptableGitDir()) {
      return { cwd, warning: null };
    }
    const reason =
      renameError instanceof Error ? renameError.message : String(renameError);
    throw new Error(
      `Failed to move managed checkout into place at "${cwd}": ${reason}`,
    );
  }
  return { cwd, warning: null };
}

/**
 * Resolve one project workspace row to a usable cwd. The anchor path and each additional
 * referenced project share this step: use the configured cwd when present, otherwise clone or
 * create the managed checkout directory for the project. It throws only when the managed
 * checkout cannot be prepared (for example, a clone failure).
 */
async function resolveConfiguredOrManagedProjectCwd(input: {
  companyId: string;
  projectId: string;
  cwd: string | null;
  repoUrl: string | null;

View on GitHub (pinned to 01ad858492)

Solutions

1. Restore the expected managed branch in the worktree, or record a sanctioned branch transition, then retry.

When it happens

Trigger: Thrown at server/src/services/heartbeat.ts:2134 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/0b15bc64ff266863. Report an issue: GitHub.