paperclipai/paperclip · error · Error

Worktree seed source is not registered. Managed boot require

Error message

Worktree seed source is not registered. Managed boot requires a project workspace; manual boot requires --from-config.

What it means

resolveRegisteredWorktreeSeedSource() needs to know which Paperclip instance to seed from, and it got neither a registered base workspace cwd nor an explicit --from-config path. Managed boot derives the source from a registered project workspace; manual boot requires an explicit config, and with both absent there is nothing authoritative to resolve.

Source

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

    throw new Error(`${label} does not exist at ${resolved}.`);
  }
  if (canonical !== resolved || lstatSync(resolved).isSymbolicLink()) {
    throw new Error(`${label} must be a canonical path and cannot use a symlink alias.`);
  }
  if (!lstatSync(canonical).isFile()) {
    throw new Error(`${label} is not a regular file at ${canonical}.`);
  }
  return canonical;
}

/** Resolve the authoritative source and target identities without consulting diagnostics. */
export function resolveRegisteredWorktreeSeedSource(
  input: RegisteredWorktreeSeedSourceInput,
): CanonicalWorktreeSeedSource {
  const registeredCwd = input.registeredBaseWorkspaceCwd?.trim();
  const explicitSource = input.explicitSourceConfigPath?.trim();
  if (!registeredCwd && !explicitSource) {
    throw new Error(
      "Worktree seed source is not registered. Managed boot requires a project workspace; manual boot requires --from-config.",
    );
  }

  let canonicalBaseCwd: string | null = null;
  let registeredConfigPath: string | null = null;
  if (registeredCwd) {
    const resolvedRegisteredCwd = path.resolve(registeredCwd);
    try {
      canonicalBaseCwd = realpathSync(resolvedRegisteredCwd);
    } catch {
      throw new Error(`Registered base project workspace does not exist at ${resolvedRegisteredCwd}.`);
    }
    if (canonicalBaseCwd !== resolvedRegisteredCwd) {
      throw new Error("Registered base project workspace must be canonical and cannot use a symlink alias.");
    }
    if (!lstatSync(canonicalBaseCwd).isDirectory()) {
      throw new Error(`Registered base project workspace is not a directory at ${canonicalBaseCwd}.`);

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Run the command from inside a registered project workspace (one known to the Paperclip instance), or re-register it.
2. Pass an explicit source: add `--from-config <path-to-config.json>` pointing at a valid instance config.
3. If you expected a registration to exist, check the instance's registered workspaces list to see whether the cwd matches.

Example fix

# before
paperclip worktree seed   # run from /tmp, no registration, no flag

# after
paperclip worktree seed --from-config ~/.paperclip/instances/<instance-id>/config.json

const hasSeedSource = Boolean(
  (input.registeredBaseWorkspaceCwd ?? "").trim() ||
  (input.explicitSourceConfigPath ?? "").trim(),
);
if (!hasSeedSource) {
  throw new Error("pass --from-config or run inside a registered workspace");
}

type SeedInput =
  | { registeredBaseWorkspaceCwd: string; explicitSourceConfigPath?: string }
  | { registeredBaseWorkspaceCwd?: null; explicitSourceConfigPath: string };

const hasRequiredSeedSource = (i: RegisteredWorktreeSeedSourceInput): i is SeedInput =>
  Boolean(i.registeredBaseWorkspaceCwd?.trim() ?? i.explicitSourceConfigPath?.trim());

When it happens

Trigger: Calling worktree-seed resolution with `registeredBaseWorkspaceCwd` null/blank and `explicitSourceConfigPath` null/blank; running the seed command in a scratch directory that is not a registered project workspace and without --from-config.

Common situations: Running `paperclip worktree ...` from a fresh clone or /tmp with no prior `paperclip register/init`; CI jobs starting in a clean checkout; whitespace-only registration values after a config edit; scripts that conditionally pass --from-config and skip it in one branch.

Related errors

• Registered base project workspace has no Paperclip config of
• Explicit source Paperclip config does not match the register
• Unknown config key ${warning.path}; did you mean ${warning.s
• Unknown config key ${warning.path}; did you mean ${warning.s
• Registered base project workspace Paperclip config at ${conf

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