{"record":{"id":"6dbd3b19cab9ade0","repo":"paperclipai/paperclip","slug":"detection-reason","errorCode":null,"errorMessage":"${detection.reason}","messagePattern":"\\$\\{detection\\.reason\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/service.ts","lineNumber":156,"sourceCode":"  const reportPath = path.join(resolvePaperclipInstanceRoot(instanceId), \"hot-restart-report.json\");\n  const deadline = Date.now() + timeoutMs;\n  while (Date.now() < deadline) {\n    try {\n      const report = JSON.parse(await fs.readFile(reportPath, \"utf8\")) as { requestedAt?: unknown };\n      if (report.requestedAt === requestedAt) return report;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n    }\n    await new Promise((resolve) => setTimeout(resolve, 250));\n  }\n  return null;\n}\n\nexport async function restartManagedService(input: { instanceId?: string; expectedVersion?: string | null; waitForDrain?: boolean } = {}): Promise<{ status: ServiceStatus; health: HealthResult; report: unknown | null }> {\n  const instanceId = resolvePaperclipInstanceId(input.instanceId);\n  return withHotRestartLock(instanceId, async () => {\n    const detection = await detectServiceManager({ instanceId });\n    if (!detection.supported) throw new Error(detection.reason);\n    const before = await detection.manager.status();\n    const intent = await writeHotRestartIntent(before, instanceId, input.waitForDrain ?? false);\n    await detection.manager.restart();\n    const health = await waitForHealth(instanceId, resolveRestartExpectedVersion(input.expectedVersion));\n    return { status: await detection.manager.status(), health, report: await waitForRestartReport(instanceId, intent.requestedAt) };\n  });\n}\n\nexport function registerServiceCommands(program: Command): void {\n  const service = program.command(\"service\").description(\"Manage Paperclip as a background service\");\n  const common = (command: Command) => command.option(\"-i, --instance <id>\", \"Local instance id (default: default)\").option(\"--json\", \"Print machine-readable JSON\", false);\n\n  common(service.command(\"install\").description(\"Install and register the background service\"))\n    .option(\"--no-start-now\", \"Install without starting now\")\n    .option(\"--no-start-on-login\", \"Install without enabling start on login\")\n    .option(\"--enable-linger\", \"Allow systemd startup without an active login session\", false)\n    .action(async (opts) => {\n      const manager = await resolveManager(opts); if (!manager) return;","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/service.ts#L138-L174","documentation":"Thrown by restartManagedService() when detectServiceManager() returns `{supported: false}`. The message is the detection's own `reason` string, which explains why no supported service supervisor (systemd on Linux, launchd on macOS) was found for this instance.","triggerScenarios":"Running `paperclipai service restart` on a platform without systemd or launchd, or where the service was never installed, or detection cannot find the unit. The thrown value is `detection.reason` produced by detectServiceManager().","commonSituations":"Unsupported OS (e.g. Windows or a minimal container without systemd/launchd), WSL without systemd enabled, or attempting service commands before `service install` has been run.","solutions":["Install the service first: `paperclipai service install`.","On Linux without systemd, enable systemd (WSL: `/etc/wsl.conf` `[boot] systemd=true`) or run the server in the foreground with `paperclipai run`.","Read detection.reason for the platform-specific cause and address it."],"exampleFix":"# before: restart on unsupported platform\npaperclipai service restart\n# after: install, or run foreground\npaperclipai service install\npaperclipai service restart\n# or\npaperclipai run","handlingStrategy":"validation","validationCode":"const detection = await detectServiceManager({instanceId});\nif (!detection.supported) {\n  throw new Error(`Service manager unsupported: ${detection.reason}`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `service install` before `service restart`.","On minimal/container Linux, prefer foreground `paperclipai run` over service management."],"tags":["service","platform","unsupported","restart","supervisor"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}