{"record":{"id":"7fe7d31928fc884a","repo":"paperclipai/paperclip","slug":"paperclip-instance-instanceid-is-already-runn","errorCode":null,"errorMessage":"Paperclip instance '${instanceId}' is already running as ${status.serviceName}. Use 'paperclipai service status --instance ${instanceId}' or pass --force to bypass this safety check.","messagePattern":"Paperclip instance '(.+?)' is already running as (.+?)\\. Use 'paperclipai service status --instance (.+?)' or pass --force to bypass this safety check\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"cli/src/services/service-manager.ts","lineNumber":310,"sourceCode":"  const instanceId = resolvePaperclipInstanceId(input.instanceId);\n  const platform = input.platform ?? process.platform;\n  const runner = input.runner ?? defaultCommandRunner;\n  if (platform === \"darwin\") return { supported: true, manager: new LaunchdServiceManager(instanceId, runner) };\n  if (platform !== \"linux\") return { supported: false, reason: `Service management is not supported on ${platform}. Use paperclipai run instead.` };\n  try {\n    await runner(\"systemctl\", [\"--user\", \"show-environment\"]);\n    return { supported: true, manager: new SystemdServiceManager(instanceId, runner) };\n  } catch {\n    return { supported: false, reason: \"No usable systemd user manager was detected (common in containers and WSL1). Use paperclipai run instead.\" };\n  }\n}\n\nexport async function assertForegroundRunAllowed(instanceId: string, force = false, detector: typeof detectServiceManager = detectServiceManager): Promise<void> {\n  if (force || process.env.PAPERCLIP_SERVICE_MANAGED === \"1\") return;\n  const detection = await detector({ instanceId });\n  if (!detection.supported) return;\n  const status = await detection.manager.status();\n  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.`);\n}\n","sourceCodeStart":292,"sourceCodeEnd":312,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/services/service-manager.ts#L292-L312","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Stop the existing service first: 'paperclipai service stop --instance <instanceId>'.","If you intentionally want to run in foreground alongside or instead of the service, pass --force: 'paperclipai run --force'.","Uninstall the service if you no longer want it managed: 'paperclipai service uninstall'.","Check service status to confirm: 'paperclipai service status --instance <instanceId>'."],"exampleFix":"// before: duplicate run attempt\n// paperclipai run --instance default\n// Error: already running as paperclipai.service\n\n// after: stop the service first, then run\n// paperclipai service stop --instance default\n// paperclipai run --instance default\n\n// or bypass the safety check:\n// paperclipai run --instance default --force","handlingStrategy":"validation","validationCode":"import { detectServiceManager } from './service-manager.js';\n\nasync function isInstanceAlreadyRunning(instanceId: string): Promise<boolean> {\n  const detection = await detectServiceManager({ instanceId });\n  if (!detection.supported) return false;\n  const status = await detection.manager.status();\n  return status.active;\n}\n\n// Call before paperclipai run (or assertForegroundRunAllowed):\nif (await isInstanceAlreadyRunning(instanceId)) {\n  console.warn('Instance is already running as a service. Use --force or stop the service first.');\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await assertForegroundRunAllowed(instanceId);\n  // proceed with foreground run\n} catch (error) {\n  if (error instanceof Error && error.message.includes('already running')) {\n    // Option 1: stop the service first\n    // Option 2: pass --force to bypass\n    console.error(error.message);\n    console.error('Run with --force to bypass, or stop the service first.');\n    process.exit(1);\n  }\n  throw error;\n}","preventionTips":["Before running 'paperclipai run', check if the service is active: 'paperclipai service status --instance <id>'.","Use 'paperclipai service stop' before switching from service mode to foreground mode.","Set PAPERCLIP_SERVICE_MANAGED=1 in the environment if running inside the service itself (the check auto-bypasses).","Pass --force when you intentionally need a foreground run alongside or instead of the service."],"tags":["service-manager","duplicate-instance","safety","cli"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}