paperclipai/paperclip · error · Error

Managed worktree seed registration is incomplete; project wo

Error message

Managed worktree seed registration is incomplete; project workspace and company bindings are required.

What it means

For a managed (registered-base-workspace) reseed with no explicit source config, ensureWorktreeSeeded requires both a project workspace binding (opts.registeredProjectWorkspaceId or PAPERCLIP_PROJECT_WORKSPACE_ID) and a company binding (opts.expectedCompanyId, PAPERCLIP_SEED_EXPECTED_COMPANY_ID, or PAPERCLIP_COMPANY_ID). Without both, the seed cannot prove which workspace and company the clone belongs to, so it refuses rather than seed with ambiguous identity.

Source

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

  const registeredBaseWorkspaceCwd = opts.registeredBaseWorkspaceCwd
    ?? nonEmpty(process.env.PAPERCLIP_WORKSPACE_BASE_CWD)
    ?? null;
  if (!initialManifest && !legacyPending && !hasExplicitSource && !registeredBaseWorkspaceCwd) {
    if (existsSync(markers.lock)) {
      const releaseExistingLock = await acquireWorktreeSeedLock(markers.lock);
      await releaseExistingLock();
    }
    return { seeded: false, reason: "legacy_unmarked" };
  }
  const registeredProjectWorkspaceId = opts.registeredProjectWorkspaceId
    ?? nonEmpty(process.env.PAPERCLIP_PROJECT_WORKSPACE_ID)
    ?? null;
  const expectedCompanyId = opts.expectedCompanyId
    ?? nonEmpty(process.env.PAPERCLIP_SEED_EXPECTED_COMPANY_ID)
    ?? nonEmpty(process.env.PAPERCLIP_COMPANY_ID)
    ?? undefined;
  if (!explicitSourceConfigPath && registeredBaseWorkspaceCwd && (!registeredProjectWorkspaceId || !expectedCompanyId)) {
    throw new Error(
      "Managed worktree seed registration is incomplete; project workspace and company bindings are required.",
    );
  }

  const targetRoot = path.dirname(path.dirname(configPath));
  const targetPaths = resolveWorktreeReseedTargetPaths({ configPath, rootPath: targetRoot });
  const registeredSeedSource = resolveRegisteredWorktreeSeedSource({
    registeredBaseWorkspaceCwd,
    explicitSourceConfigPath,
    targetConfigPath: configPath,
    expectedTargetInstanceId: targetPaths.instanceId,
  });

  if (initialManifest && initialManifest.targetInstanceId !== registeredSeedSource.targetInstanceId) {
    throw new Error("Worktree seed manifest target instance does not match the registered target instance.");
  }

  // Resolve all authority-bearing paths before creating the lock. The manifest is

View on GitHub (pinned to a7e689b3c3)

Solutions

Set PAPERCLIP_PROJECT_WORKSPACE_ID and PAPERCLIP_COMPANY_ID (or PAPERCLIP_SEED_EXPECTED_COMPANY_ID) in the worktree service environment and retry
Or pass an explicit source config path so the seed does not depend on registration bindings
Or re-register / recreate the worktree so the registration stamps complete bindings

Example fix

# before (worktree service env)
PAPERCLIP_CONFIG=/worktrees/foo/paperclip.config.json

# after
PAPERCLIP_CONFIG=/worktrees/foo/paperclip.config.json
PAPERCLIP_PROJECT_WORKSPACE_ID=ws_123
PAPERCLIP_COMPANY_ID=comp_456

Defensive patterns

Strategy: validation

Validate before calling

const needWorkspace = process.env.PAPERCLIP_PROJECT_WORKSPACE_ID;
const needCompany = process.env.PAPERCLIP_SEED_EXPECTED_COMPANY_ID ?? process.env.PAPERCLIP_COMPANY_ID;
if (registeredBaseWorkspaceCwd && !explicitSource && (!needWorkspace || !needCompany)) {
  throw new Error('Seed registration bindings missing: set PAPERCLIP_PROJECT_WORKSPACE_ID and PAPERCLIP_COMPANY_ID.');
}

Prevention

Stamp the full registration env (workspace id + company id) into every worktree service definition at creation time
Smoke-test worktree services with `ensure-seeded` right after registration

When it happens

Trigger: Running worktree ensure-seeded from a worktree whose registered base workspace cwd is known, but the process env lacks PAPERCLIP_PROJECT_WORKSPACE_ID and the company vars, and no --source config path was passed — e.g. a service started with an incomplete environment, or a manual invocation outside the service wrapper.

Common situations: A worktree service whose env was hand-copied and dropped the registration vars; recreating a service unit without the registration block; moving a worktree registration to a new machine without its env.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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