paperclipai/paperclip · error

Cannot restart ${status.serviceName}: supervisor did not rep

Error message

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

What it means

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.

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 67001ec6eb)

Solutions

1. Start the service first: `paperclipai service start`, then restart.
2. Check status to see why no pid: `paperclipai service status`.
3. If the pid file is stale, reinstall or re-install the service unit, then start.

Example fix

# before: hot-restart on a stopped service
paperclipai service restart
# after: start then restart
paperclipai service start
paperclipai service restart

function assertPid(status: {pid?: number | null}, serviceName: string): void {
  if (!status.pid) throw new Error(`Cannot restart ${serviceName}: no server pid.`);
}

function statusHasPid(s: unknown): s is { pid: number } {
  return typeof (s as any)?.pid === 'number' && (s as any).pid > 0;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${detection.reason}
• Paperclip service did not become healthy${expectedVersion ?
• Another restart for instance ${instanceId} is still running.
• ${manager.serviceName} is still loaded after uninstall.
• --lines must be a positive integer.

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