paperclipai/paperclip · error · Error

Failed to merge concurrent remote git histories for ${curren

Error message

Failed to merge concurrent remote git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}

What it means

Thrown by integrateImportedGitHead when `git merge-tree --write-tree <currentHead> <importedHead>` fails with an error. This happens during workspace sync when the local head and the imported remote head have divergent histories that git cannot auto-merge (true merge conflicts) or when git itself errors (corrupt repo, invalid refs).

Source

Thrown at packages/adapter-utils/src/git-workspace-sync.ts:426

          timeout: 10_000,
          maxBuffer: 16 * 1024,
        });
        return;
      } catch (error) {
        if (isConcurrentRefUpdateError(error) && attempt < 4) continue;
        throw error;
      }
    }

    let mergedTree;
    try {
      mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
        timeout: 60_000,
        maxBuffer: 256 * 1024,
      });
    } catch (error) {
      const reason = error instanceof Error ? error.message : String(error);
      throw new Error(
        `Failed to merge concurrent remote git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`,
      );
    }
    const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
    if (!mergedTreeId) {
      throw new Error("Failed to compute a merged git tree for workspace restore.");
    }

    const mergeCommit = await runLocalGit(
      input.localDir,
      [
        "commit-tree",
        mergedTreeId,
        "-p",
        currentHead,
        "-p",
        input.importedHead,
        "-m",

View on GitHub (pinned to 67001ec6eb)

Solutions

Check the reason string in the error message for git's conflict details and resolve the conflicting files.
Ensure the local git repo is healthy (git fsck) and HEAD points to a valid commit.
Upgrade git to 2.38+ if `merge-tree --write-tree` is not supported.
If conflicts are due to concurrent agents, serialize workspace access or partition work to avoid overlapping file edits.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check for merge conflicts before integrating
async function canMergeWithoutConflict(localDir: string, currentHead: string, importedHead: string): Promise<boolean> {
  try {
    const result = await runLocalGit(localDir, ["merge-tree", "--write-tree", currentHead, importedHead], {
      timeout: 60_000,
      maxBuffer: 256 * 1024,
    });
    return result.stdout.trim().length > 0;
  } catch {
    return false;
  }
}

Try / catch

try {
  await integrateImportedGitHead({ localDir, importedHead });
} catch (err) {
  if (err instanceof Error && err.message.includes("Failed to merge concurrent remote git histories")) {
    // Fall back to a hard reset or manual conflict resolution
    logger.error(`Git merge conflict during workspace sync: ${err.message}`);
    throw err;
  }
  throw err;
}

Prevention

Serialize workspace sync operations to avoid concurrent divergent histories.
Partition agent work to minimize overlapping file edits between concurrent runs.
Run `git fsck` periodically to maintain repo health.
Ensure git 2.38+ is installed for merge-tree --write-tree support.

When it happens

Trigger: Calling integrateImportedGitHead({ localDir, importedHead }) where the merge-base check shows the two heads have diverged (neither is an ancestor of the other). The subsequent `git merge-tree --write-tree` invocation throws, and the error message is captured into the reason.

Common situations: Two concurrent agent runs modified overlapping files causing a content conflict; the local git repo is corrupt or has a detached HEAD in an unexpected state; the importedHead SHA is invalid or points to a different repo; git version is too old to support `merge-tree --write-tree` (requires git 2.38+).

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/6b63f1d2e924b961. Report an issue: GitHub.