paperclipai/paperclip · warning · Error

Paperclip instance '${instanceId}' is already running as ${s

Error message

Paperclip instance '${instanceId}' is already running as ${status.serviceName}. Use 'paperclipai service status --instance ${instanceId}' or pass --force to bypass this safety check.

What it means

Thrown by assertForegroundRunAllowed when a 'paperclipai run' foreground invocation detects that the same instance is already active as a managed system service (systemd or launchd). This prevents accidental duplicate instances that would conflict on ports, locks, and state. The check is bypassed by passing --force or setting PAPERCLIP_SERVICE_MANAGED=1.

Source

Thrown at cli/src/services/service-manager.ts:310

  const instanceId = resolvePaperclipInstanceId(input.instanceId);
  const platform = input.platform ?? process.platform;
  const runner = input.runner ?? defaultCommandRunner;
  if (platform === "darwin") return { supported: true, manager: new LaunchdServiceManager(instanceId, runner) };
  if (platform !== "linux") return { supported: false, reason: `Service management is not supported on ${platform}. Use paperclipai run instead.` };
  try {
    await runner("systemctl", ["--user", "show-environment"]);
    return { supported: true, manager: new SystemdServiceManager(instanceId, runner) };
  } catch {
    return { supported: false, reason: "No usable systemd user manager was detected (common in containers and WSL1). Use paperclipai run instead." };
  }
}

export async function assertForegroundRunAllowed(instanceId: string, force = false, detector: typeof detectServiceManager = detectServiceManager): Promise<void> {
  if (force || process.env.PAPERCLIP_SERVICE_MANAGED === "1") return;
  const detection = await detector({ instanceId });
  if (!detection.supported) return;
  const status = await detection.manager.status();
  if (status.active) throw new Error(`Paperclip instance '${instanceId}' is already running as ${status.serviceName}. Use 'paperclipai service status --instance ${instanceId}' or pass --force to bypass this safety check.`);
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Stop the existing service first: 'paperclipai service stop --instance <instanceId>'.
2. If you intentionally want to run in foreground alongside or instead of the service, pass --force: 'paperclipai run --force'.
3. Uninstall the service if you no longer want it managed: 'paperclipai service uninstall'.
4. Check service status to confirm: 'paperclipai service status --instance <instanceId>'.

Example fix

// before: duplicate run attempt
// paperclipai run --instance default
// Error: already running as paperclipai.service

// after: stop the service first, then run
// paperclipai service stop --instance default
// paperclipai run --instance default

// or bypass the safety check:
// paperclipai run --instance default --force

import { detectServiceManager } from './service-manager.js';

async function isInstanceAlreadyRunning(instanceId: string): Promise<boolean> {
  const detection = await detectServiceManager({ instanceId });
  if (!detection.supported) return false;
  const status = await detection.manager.status();
  return status.active;
}

// Call before paperclipai run (or assertForegroundRunAllowed):
if (await isInstanceAlreadyRunning(instanceId)) {
  console.warn('Instance is already running as a service. Use --force or stop the service first.');
  process.exit(1);
}

try {
  await assertForegroundRunAllowed(instanceId);
  // proceed with foreground run
} catch (error) {
  if (error instanceof Error && error.message.includes('already running')) {
    // Option 1: stop the service first
    // Option 2: pass --force to bypass
    console.error(error.message);
    console.error('Run with --force to bypass, or stop the service first.');
    process.exit(1);
  }
  throw error;
}

When it happens

Trigger: Running 'paperclipai run' (or any code calling assertForegroundRunAllowed without force=true) when the instance's systemd/launchd service reports status.active === true. The function detects the service manager, queries its status, and throws if it is already running.

Common situations: The user previously ran 'paperclipai service install --start-now' and forgot, then tries to run in foreground. The service auto-started on login via systemd/launchd. A previous foreground run was migrated to a service. The user is debugging and wants to run manually without stopping the service.

Related errors

• Safety checks failed. Resolve the issues above or re-run wit
• Refusing to replace existing non-managed command ${paths.shi
• Systemd service values must not contain line breaks
• Refusing to write service definition through unsafe director
• Refusing to write service definition in directory not owned

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/7fe7d31928fc884a. Report an issue: GitHub.