paperclipai/paperclip · error · Error

Cannot restart : supervisor did not report a server pid.

Error message

Cannot restart ${status.serviceName}: supervisor did not report a server pid.

What it means

writeHotRestartIntent needs the running server's pid to signal a hot restart, but the service status reported none, so the restart intent cannot be delivered.

Solutions

1. Check the supervisor/service status; start the service or reinstall it so a pid is reported.

When it happens

Trigger: Thrown at cli/src/commands/service.ts:120 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at cli/src/commands/service.ts:120

      await new Promise((resolve) => setTimeout(resolve, pollMs));
    }
  }

  try {
    return await callback();
  } finally {
    try {
      if ((await fs.readFile(lockPath, "utf8")).trim() === token) {
        await fs.rm(lockPath, { force: true });
      }
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
    }
  }
}

async function writeHotRestartIntent(status: ServiceStatus, instanceId: string, drainRequired: boolean): Promise<{ requestedAt: string }> {
  if (!status.pid) throw new Error(`Cannot restart ${status.serviceName}: supervisor did not report a server pid.`);
  const health = await probeHealth(instanceId);
  const instanceRoot = resolvePaperclipInstanceRoot(instanceId);
  const requestedAt = new Date().toISOString();
  await fs.mkdir(instanceRoot, { recursive: true });
  await fs.rm(path.join(instanceRoot, "hot-restart-report.json"), { force: true });
  await fs.writeFile(path.join(instanceRoot, "hot-restart-intent.json"), `${JSON.stringify({
    version: 1,
    requestedAt,
    previousServerPid: status.pid,
    previousServerVersion: health.serverVersion,
    drainRequired,
    requestedByRunId: process.env.PAPERCLIP_RUN_ID?.trim() || null,
  }, null, 2)}\n`, "utf8");
  return { requestedAt };
}

async function waitForRestartReport(instanceId: string, requestedAt: string, timeoutMs = 10_000): Promise<unknown | null> {
  const reportPath = path.join(resolvePaperclipInstanceRoot(instanceId), "hot-restart-report.json");

View on GitHub (pinned to 120ae5428f)