paperclipai/paperclip · critical

hot_restart_intent_failed

Error message

hot_restart_intent_failed

What it means

This is an HTTP 500 JSON error from POST /dev-server/restart. After preflighting active runs, the route writes a hot-restart intent (writeHotRestartIntent) and a dev-server restart request file, rolling both back on failure. Any error during this coordination that is NOT the known "dev_server_supervisor_unavailable" case is logged and surfaced as `hot_restart_intent_failed` with status 500 — meaning the restart was requested but the two-phase intent/request handshake failed and was rolled back.

Source

Thrown at server/src/routes/health.ts:220

      if (intent) {
        await removeHotRestartIntent(undefined, intent).catch(
          (rollbackError) => {
            logger.error(
              { err: rollbackError, requestId },
              "failed to roll back hot-restart intent",
            );
          },
        );
      }
      if (
        error instanceof Error &&
        error.message === "dev_server_supervisor_unavailable"
      ) {
        res.status(404).json({ error: "dev_server_supervisor_unavailable" });
        return;
      }
      logger.error({ err: error, requestId }, "failed to coordinate hot restart request");
      res.status(500).json({ error: "hot_restart_intent_failed" });
      return;
    }

    res.status(202).json({
      status: "restart_requested",
      requestId,
      mode: "hot",
    });
  });

  router.get("/", async (req, res) => {
    const actorType = "actor" in req ? req.actor?.type : null;
    const exposeFullDetails = shouldExposeFullHealthDetails(
      actorType,
      opts.deploymentMode,
    );
    const runtimeEnv = opts.runtimeEnv ?? process.env;
    const startupRecovery = getStartupRecoveryState();

View on GitHub (pinned to 01ad858492)

Solutions

1. Check server logs for "failed to coordinate hot restart request" — the logged err names the underlying cause (DB vs filesystem).
2. Verify the dev-server supervisor status directory exists and is writable by the server process.
3. If the intent write failed on DB, check database health and connectivity, then retry the restart.
4. Ensure no concurrent restart requests are in flight; retry once the previous one resolves.
5. Fall back to a cold stop/start of the dev server if hot-restart coordination keeps failing.

Example fix

// before: blind retry of the hot restart
await api.post('/api/dev-server/restart');
// after: check writability and supervisor status first, then retry
const status = readPersistedDevServerStatus();
if (!status) return coldRestart();
await api.post('/api/dev-server/restart'); // retry only after cause is fixed

// preflight before requesting a hot restart
const writable = fs.accessSync(devServerStatusDir, fs.constants.W_OK); // throws if not writable
const disk = checkDiskSpace(devServerStatusDir);
if (disk.free < minRequiredBytes) throw new Error('insufficient disk for restart intent');

function isHotRestartIntentFailed(body: unknown): body is { error: 'hot_restart_intent_failed' } {
  return typeof body === 'object' && body !== null && (body as any).error === 'hot_restart_intent_failed';
}

const res = await api.post('/api/dev-server/restart');
if (res.status === 500 && isHotRestartIntentFailed(await res.json())) {
  logger.error('hot restart coordination failed and was rolled back; falling back to cold restart');
  return coldRestartServer();
}

When it happens

Trigger: POST /api/dev-server/restart when writeHotRestartIntent throws (DB write of the intent row fails) or writeDevServerRestartRequest returns false/unexpected filesystem error — other than the specifically mapped supervisor-unavailable case — e.g., permissions on the restart-request path, disk full, DB write failure mid-intent.

Common situations: Read-only or deleted dev-server status directory so the restart request file can't be written; disk quota exhausted; DB connection dropped between the preflight query and the intent write; concurrent restarts colliding on the same request file; running the server from a path the supervisor cannot manage.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Plugin UI directory not found
• Failed to serve file
• Registered ${label} Paperclip config is missing its adjacent
• Registered base project workspace Paperclip config at ${conf
• Registered base project workspace Paperclip config at ${conf

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/3b104d65334bd9a0. Report an issue: GitHub.