Refusing to record worktree instance ownership for "${config

Error message

Refusing to record worktree instance ownership for "${configured.instanceRoot}" because it is outside "${managedInstancesDir}".

What it means

The worktree instance pointer names an instance root outside the managed instances directory, so ownership recording is refused. This safety check prevents Paperclip from tracking (and later cleaning up) directories it does not manage.

Source

Thrown at server/src/services/workspace-instance-cleanup.ts:259

    ),
  );
  return path.join(managedWorktreesDir, "instances");
}

export async function readManagedWorktreeInstanceOwnership(
  workspacePath: string,
  worktreesDir?: string,
): Promise<{ instanceRoot: string; instanceId: string } | null> {
  const pointer = await readWorktreeInstancePointer(workspacePath);
  if (!pointer) return null;
  const configured = resolveConfiguredInstanceRoot(pointer);
  if ("warning" in configured) {
    if (!configured.warning) return null;
    throw new Error(configured.warning);
  }
  const managedInstancesDir = resolveManagedInstancesDir(worktreesDir);
  if (!isStrictChildPath(configured.instanceRoot, managedInstancesDir)) {
    throw new Error(
      `Refusing to record worktree instance ownership for "${configured.instanceRoot}" because it is outside "${managedInstancesDir}".`,
    );
  }
  return configured;
}

export async function cleanupWorktreeInstanceArtifacts(input: {
  pointer: WorktreeInstancePointer;
  workspaceId: string;
  workspacePath: string;
  expectedInstanceId: string;
  expectedInstanceRoot: string | null;
  recorder?: WorkspaceOperationRecorder | null;
  worktreesDir?: string;
  dependencies?: WorktreeInstanceCleanupDependencies;
}): Promise<WorktreeInstanceCleanupResult> {
  const configured = resolveConfiguredInstanceRoot(input.pointer, input.expectedInstanceId);
  if ("warning" in configured && !configured.warning) return { status: "not_configured" };

View on GitHub (pinned to a7e689b3c3)

Solutions

The instance root lies outside the managed instances directory. Move the instance under the managed directory or fix the instanceRoot configuration.

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/src/services/workspace-instance-cleanup.ts:237 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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