paperclipai/paperclip · error · Error

Invalid worktree seed-pending marker at ${filePath}.

Error message

Invalid worktree seed-pending marker at ${filePath}.

What it means

Thrown by readWorktreeSeedPendingMarker when the pending marker parses as JSON but fails the structural validation: it must be an object with version===1, state==='pending', and a non-empty string sourceConfigPath. Any deviation means the marker is from an incompatible version or hand-mangled.

Source

Thrown at cli/src/commands/worktree.ts:1452

function readWorktreeSeedPendingMarker(filePath: string): WorktreeSeedPendingMarker {
  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(filePath, "utf8"));
  } catch (error) {
    throw new Error(
      `Invalid worktree seed-pending marker at ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
    );
  }

  if (
    !parsed
    || typeof parsed !== "object"
    || (parsed as { version?: unknown }).version !== 1
    || (parsed as { state?: unknown }).state !== "pending"
    || typeof (parsed as { sourceConfigPath?: unknown }).sourceConfigPath !== "string"
    || !(parsed as { sourceConfigPath: string }).sourceConfigPath.trim()
  ) {
    throw new Error(`Invalid worktree seed-pending marker at ${filePath}.`);
  }

  return parsed as WorktreeSeedPendingMarker;
}

const WORKTREE_SEED_LOCK_POLL_MS = 50;
const WORKTREE_SEED_LOCK_MALFORMED_STALE_MS = 60_000;

type WorktreeSeedLockOwner = {
  version: 1;
  pid: number;
  token: string;
  createdAt: string;
};

function processIsAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Delete the invalid pending marker and re-run init/reseed so a conformant marker is written.
2. Upgrade or downgrade the CLI to a version whose marker schema matches the file.
3. If migrating formats, write a conversion shim or remove legacy markers before upgrading.
4. Avoid manually editing marker files.

Example fix

# before: marker with state: 'old'
# after
rm .paperclip/seed-pending.json && paperclipai worktree init ...

function isValidPendingMarker(filePath: string): boolean {
  try {
    const p = JSON.parse(fs.readFileSync(filePath, 'utf8'));
    return p && p.version === 1 && p.state === 'pending' && typeof p.sourceConfigPath === 'string' && p.sourceConfigPath.trim().length > 0;
  } catch { return false; }
}

function isWorktreeSeedPendingMarker(v: unknown): v is WorktreeSeedPendingMarker {
  return !!v && typeof v === 'object' && (v as any).version === 1 && (v as any).state === 'pending' && typeof (v as any).sourceConfigPath === 'string' && (v as any).sourceConfigPath.trim().length > 0;
}

if (!isValidPendingMarker(markers.pending)) {
  fs.rmSync(markers.pending, { force: true });
  // re-trigger seed
}

When it happens

Trigger: An older/newer marker format with a different version field; a complete marker accidentally renamed to the pending path; state field set to something other than 'pending'; sourceConfigPath missing, empty, or non-string.

Common situations: Version skew after upgrading the CLI that changed the marker schema; marker from a different tool written to the same path; manual edit removing a required field; pending marker overwritten by a complete marker due to a bug.

Related errors

• Invalid worktree seed-pending marker at ${filePath}: ${error
• Worktree seed lock ${lockPath} belongs to exited process ${c
• Worktree seed lock ${lockPath} is stale or malformed. Verify
• Source and target Paperclip configs are the same. Pass --fro
• Import transfer declaration returned no data.

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