{"record":{"id":"9000af51b364171f","repo":"paperclipai/paperclip","slug":"cannot-restart-status-servicename-supervisor-d","errorCode":null,"errorMessage":"Cannot restart ${status.serviceName}: supervisor did not report a server pid.","messagePattern":"Cannot restart (.+?): supervisor did not report a server pid\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/service.ts","lineNumber":120,"sourceCode":"      await new Promise((resolve) => setTimeout(resolve, pollMs));\n    }\n  }\n\n  try {\n    return await callback();\n  } finally {\n    try {\n      if ((await fs.readFile(lockPath, \"utf8\")).trim() === token) {\n        await fs.rm(lockPath, { force: true });\n      }\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n    }\n  }\n}\n\nasync function writeHotRestartIntent(status: ServiceStatus, instanceId: string, drainRequired: boolean): Promise<{ requestedAt: string }> {\n  if (!status.pid) throw new Error(`Cannot restart ${status.serviceName}: supervisor did not report a server pid.`);\n  const health = await probeHealth(instanceId);\n  const instanceRoot = resolvePaperclipInstanceRoot(instanceId);\n  const requestedAt = new Date().toISOString();\n  await fs.mkdir(instanceRoot, { recursive: true });\n  await fs.rm(path.join(instanceRoot, \"hot-restart-report.json\"), { force: true });\n  await fs.writeFile(path.join(instanceRoot, \"hot-restart-intent.json\"), `${JSON.stringify({\n    version: 1,\n    requestedAt,\n    previousServerPid: status.pid,\n    previousServerVersion: health.serverVersion,\n    drainRequired,\n    requestedByRunId: process.env.PAPERCLIP_RUN_ID?.trim() || null,\n  }, null, 2)}\\n`, \"utf8\");\n  return { requestedAt };\n}\n\nasync function waitForRestartReport(instanceId: string, requestedAt: string, timeoutMs = 10_000): Promise<unknown | null> {\n  const reportPath = path.join(resolvePaperclipInstanceRoot(instanceId), \"hot-restart-report.json\");","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/service.ts#L102-L138","documentation":"Thrown by writeHotRestartIntent() when the supervisor status for the service reports no `pid`. Hot restart needs the previous server pid to write an intent file that the running server can adopt, so a missing pid aborts before any restart action.","triggerScenarios":"Calling `service restart` when the service is installed but not currently running, or the supervisor reports status without a pid (e.g. service stopped, crashed, or the manager cannot read the pid). `status.pid` is falsy at service.ts:120.","commonSituations":"Restarting a service that is stopped; supervisor lost track of the process (pid file deleted); service in a failed state. Operators assume restart will start a stopped service, but hot-restart specifically requires a live pid.","solutions":["Start the service first: `paperclipai service start`, then restart.","Check status to see why no pid: `paperclipai service status`.","If the pid file is stale, reinstall or re-install the service unit, then start."],"exampleFix":"# before: hot-restart on a stopped service\npaperclipai service restart\n# after: start then restart\npaperclipai service start\npaperclipai service restart","handlingStrategy":"validation","validationCode":"function assertPid(status: {pid?: number | null}, serviceName: string): void {\n  if (!status.pid) throw new Error(`Cannot restart ${serviceName}: no server pid.`);\n}","typeGuard":"function statusHasPid(s: unknown): s is { pid: number } {\n  return typeof (s as any)?.pid === 'number' && (s as any).pid > 0;\n}","tryCatchPattern":null,"preventionTips":["Ensure the service is started (`service start`) before invoking restart.","Check `service status` for a live pid before requesting hot restart."],"tags":["service","restart","pid","supervisor","hot-restart"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}