paperclipai/paperclip · error · Error

${label} does not exist at ${resolved}.

Error message

${label} does not exist at ${resolved}.

What it means

canonicalRegularFile() runs realpathSync on a config path and the call throws, meaning nothing exists at that resolved path. This fires for the registered source config, the explicit (--from-config) source, the target worktree config, or the manifest diagnostic path, with `${label}` naming which one is missing.

Source

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

  if (configDirEntry?.isSymbolicLink()) {
    try {
      statSync(configDir);
    } catch (error) {
      throw new Error(
        `Registered base project workspace Paperclip config at ${configPath} cannot be inspected (${errorCode(error)} on its .paperclip symlink target).`,
      );
    }
  }
  return false;
}

function canonicalRegularFile(filePath: string, label: string): string {
  const resolved = path.resolve(filePath);
  let canonical: string;
  try {
    canonical = realpathSync(resolved);
  } catch {
    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(

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Check which label failed (source vs target vs manifest diagnostic) and `ls` that exact resolved path.
2. Re-create the missing config.json (re-run the worktree/workspace init that generates it).
3. If the path is stale, update the registration or pass the correct --from-config path.
4. For a missing target config, ensure the target worktree bootstrap runs before source resolution.

Example fix

# before
paperclip worktree seed --from-config ./wrong/path/config.json  # ENOENT

# after
paperclip worktree seed --from-config "$HOME/.paperclip/instances/<id>/config.json"

import { existsSync, realpathSync } from "node:fs";

function configExists(p: string): boolean {
  try { return existsSync(realpathSync(p)); } catch { return false; }
}

// before resolving:
if (!configExists(sourcePath) || !configExists(targetConfigPath)) {
  throw new Error("seed configs missing — re-run worktree init");
}

import { statSync } from "node:fs";
const isReadableFile = (p: string): p is string => {
  try { return statSync(p).isFile(); } catch { return false; }
};

try {
  return resolveRegisteredWorktreeSeedSource(input);
} catch (e) {
  if (e instanceof Error && /does not exist at/.test(e.message)) {
    return null; // caller decides: re-init worktree or prompt for --from-config
  }
  throw e;
}

When it happens

Trigger: resolveRegisteredWorktreeSeedSource with a registered/explicit source path whose file was deleted; a target worktree invoked before its `.paperclip/config.json` was created; a manifest whose diagnostic configPath points at a nonexistent file.

Common situations: Target worktree config not yet seeded; workspace or instance directory moved after registration; typo in --from-config; config removed by a clean/reset step (`rm -rf data/`) while registration still points there.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Registered base project workspace Paperclip config at ${conf
• ${label} is not a regular file at ${canonical}.
• Registered ${label} Paperclip config is missing its adjacent
• ${label} must be a canonical path and cannot use a symlink a
• Worktree seed source is not registered. Managed boot require

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