paperclipai/paperclip · error · Error

Target Paperclip instance does not match the registered work

Error message

Target Paperclip instance does not match the registered worktree instance.

What it means

Each config's instance id is read from the `.env` beside it (PAPERCLIP_INSTANCE_ID, or the instances/<id> directory name). The target worktree config's instance id must equal expectedTargetInstanceId — the instance the worktree is registered under. A mismatch means the worktree's config belongs to a different instance than the one performing the seed.

Source

Thrown at packages/shared/src/worktree-seed-source.ts:177

  if (explicitSource) {
    const canonicalExplicitSource = canonicalRegularFile(explicitSource, "Explicit source Paperclip config");
    if (canonicalExplicitSource !== canonicalSourceConfigPath) {
      throw new Error("Explicit source Paperclip config does not match the registered base project workspace.");
    }
  }

  const canonicalTargetConfigPath = canonicalRegularFile(
    input.targetConfigPath,
    "Target worktree Paperclip config",
  );
  if (canonicalSourceConfigPath === canonicalTargetConfigPath) {
    throw new Error("Source and target Paperclip configs are the same canonical file.");
  }

  const sourceInstanceId = readInstanceId(canonicalSourceConfigPath, "source");
  const targetInstanceId = readInstanceId(canonicalTargetConfigPath, "target");
  if (targetInstanceId !== input.expectedTargetInstanceId) {
    throw new Error("Target Paperclip instance does not match the registered worktree instance.");
  }
  if (sourceInstanceId === targetInstanceId) {
    throw new Error("Source and target Paperclip configs name the same instance.");
  }

  return {
    baseWorkspaceCwd: canonicalBaseCwd,
    configPath: canonicalSourceConfigPath,
    instanceId: sourceInstanceId,
    targetConfigPath: canonicalTargetConfigPath,
    targetInstanceId,
  };
}

/**
 * Resolve a worktree seed source without granting authority to the seed manifest.
 *
 * A managed caller supplies the project-workspace cwd from its server-owned row.

View on GitHub (pinned to a7e689b3c3)

Solutions

Print both ids: `grep PAPERCLIP_INSTANCE_ID <target>/.paperclip/.env` vs the registered worktree instance id.
Correct the target worktree's `.paperclip/.env` to the registered instance id (or re-create the worktree through the normal flow so it is registered consistently).
If the worktree was intentionally migrated, update its registration to the instance the config names.

Example fix

# before: worktree .env still names the old instance
cat worktrees/issue-42/.paperclip/.env   # PAPERCLIP_INSTANCE_ID=old-id

# after
sed -i 's/^PAPERCLIP_INSTANCE_ID=.*/PAPERCLIP_INSTANCE_ID=<registered-id>/' worktrees/issue-42/.paperclip/.env

Defensive patterns

Strategy: validation

Validate before calling

import { readFileSync } from "node:fs";

function instanceIdFromEnv(configPath: string): string | null {
  const env = readFileSync(`${configPath.replace(/config\.json$/, "")}.env`, "utf8");
  return env.match(/PAPERCLIP_INSTANCE_ID\s*=\s*["']?([^"'\s#]+)/)?.[1] ?? null;
}

const targetId = instanceIdFromEnv(targetConfigPath);
if (targetId !== expectedTargetInstanceId) throw new Error("worktree .env names another instance");

Prevention

Never copy `.paperclip/.env` between worktrees; let the tooling issue it.
Verify PAPERCLIP_INSTANCE_ID matches the registration before seeding.
After recreating an instance, audit worktrees for stale .env ids.

When it happens

Trigger: resolveRegisteredWorktreeSeedSource where the target worktree's `.paperclip/.env` has a PAPERCLIP_INSTANCE_ID different from the instance id passed in expectedTargetInstanceId; worktree registered under instance A but its config carries instance B's id.

Common situations: Worktree directory copied from another instance's worktree (bringing its .env); hand-edited .env; worktree moved between instances; seeding an old worktree after the instance was recreated with a new id.

Related errors

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-21). Data as JSON: /api/errors/7ae0a91bc4b65ced. Report an issue: GitHub.