paperclipai/paperclip · error · Error

Registered base project workspace has no Paperclip config of

Error message

Registered base project workspace has no Paperclip config of its own and no explicit source was provided.

What it means

The base workspace exists and is canonical, but declares no instance config of its own (no `.paperclip` entry), and no explicit --from-config was provided, so there is no selectable seed source. A plain checkout can serve as a base only when the caller explicitly names where to seed from.

Source

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

    } 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}.`);
    }
    // A base workspace that is a plain checkout carries no instance config of its own.
    // The caller's explicit source supplies it, and stays subject to every check below.
    registeredConfigPath = baseWorkspaceDeclaresInstanceConfig(canonicalBaseCwd)
      ? path.join(canonicalBaseCwd, ".paperclip", "config.json")
      : null;
  }

  const selectedPath = registeredConfigPath ?? explicitSource;
  if (!selectedPath) {
    throw new Error(
      "Registered base project workspace has no Paperclip config of its own and no explicit source was provided.",
    );
  }
  const canonicalSourceConfigPath = canonicalRegularFile(selectedPath, "Registered source Paperclip config");
  if (registeredConfigPath && canonicalSourceConfigPath !== registeredConfigPath) {
    throw new Error("Registered source Paperclip config escapes the base project workspace or uses a symlink alias.");
  }

  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",

View on GitHub (pinned to a7e689b3c3)

Solutions

Pass an explicit source: add `--from-config <instance>/config.json` to the seed/boot command.
Or give the base workspace its own instance config: create `.paperclip/config.json` (via the register/init flow) so it declares an instance.
Verify the `.paperclip` entry actually exists at the workspace root (`ls -la <base>/.paperclip`); note a fully absent entry is treated as 'no config', while a broken symlink entry throws earlier.

Example fix

# before: plain checkout, no .paperclip, no flag
paperclip worktree seed

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

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";
import path from "node:path";

const declaresConfig = (base: string) =>
  existsSync(path.join(base, ".paperclip", "config.json")) || existsSync(path.join(base, ".paperclip"));

if (!declaresConfig(base) && !explicitSource) {
  throw new Error("plain checkout: pass --from-config to name the seed source");
}

Prevention

Standardize team scripts to always pass --from-config for plain checkouts.
Or register checkouts once so `.paperclip/config.json` exists.
Surface a helpful hint in CLI wrappers when running in an unregistered directory.

When it happens

Trigger: Managed boot inside a plain git checkout of the project (never registered with a `.paperclip/config.json`) with the explicitSourceConfigPath argument omitted; baseWorkspaceDeclaresInstanceConfig() returning false and explicitSource empty.

Common situations: Fresh clone used as the base workspace; `.paperclip` directory deleted or never created; teams sharing a checkout without instance registration; scripts that assume managed boot works from any clone.

Related errors

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