paperclipai/paperclip · error · Error

Registered base project workspace does not exist at ${resolv

Error message

Registered base project workspace does not exist at ${resolvedRegisteredCwd}.

What it means

A registered base workspace cwd was supplied but realpathSync on it throws: nothing exists at that resolved path. The workspace the instance remembers is gone or was never valid, so the resolver cannot anchor the source config.

Source

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

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}.`);
    }
    // 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.",

View on GitHub (pinned to a7e689b3c3)

Solutions

Confirm the path exists: `ls <resolvedRegisteredCwd>`.
If the workspace moved, re-register the base workspace at its new location (or move it back).
If the workspace is intentionally gone, drop the registration or fall back to manual boot with --from-config.
On ephemeral/container setups, ensure the workspace path persists across restarts before registering.

Example fix

# before: registration still points at the old checkout path
mv ~/code/myproj ~/code/myproject   # registration now dangling

# after
paperclip register --cwd ~/code/myproject   # re-register at the new path

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from "node:fs";

if (input.registeredBaseWorkspaceCwd && !existsSync(input.registeredBaseWorkspaceCwd)) {
  throw new Error(`registered workspace ${input.registeredBaseWorkspaceCwd} is gone — re-register`);
}

Type guard

const workspaceDirExists = (cwd?: string | null): boolean =>
  Boolean(cwd?.trim()) && existsSync(cwd!.trim());

Try / catch

try {
  resolveRegisteredWorktreeSeedSource(input);
} catch (e) {
  if (e instanceof Error && /base project workspace does not exist/.test(e.message)) {
    // prompt user to re-register at the current path, or continue with --from-config
  } else throw e;
}

Prevention

Re-register workspaces right after moving or renaming them.
In containers, mount workspace paths at stable locations before registering.
Add a periodic `paperclip doctor` that stats every registered workspace cwd.

When it happens

Trigger: resolveRegisteredWorktreeSeedSource with a registeredBaseWorkspaceCwd pointing at a deleted, moved, or never-created directory.

Common situations: Workspace moved or renamed after registration; clone deleted but registration retained; mount not present (container volume, network drive); typo in a hand-edited registration; container restart with ephemeral workspace paths.

Related errors

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