{"record":{"id":"3b104d65334bd9a0","repo":"paperclipai/paperclip","slug":"hot-restart-intent-failed","errorCode":null,"errorMessage":"hot_restart_intent_failed","messagePattern":"hot_restart_intent_failed","errorType":"http","errorClass":null,"httpStatus":500,"severity":"critical","filePath":"server/src/routes/health.ts","lineNumber":220,"sourceCode":"      if (intent) {\n        await removeHotRestartIntent(undefined, intent).catch(\n          (rollbackError) => {\n            logger.error(\n              { err: rollbackError, requestId },\n              \"failed to roll back hot-restart intent\",\n            );\n          },\n        );\n      }\n      if (\n        error instanceof Error &&\n        error.message === \"dev_server_supervisor_unavailable\"\n      ) {\n        res.status(404).json({ error: \"dev_server_supervisor_unavailable\" });\n        return;\n      }\n      logger.error({ err: error, requestId }, \"failed to coordinate hot restart request\");\n      res.status(500).json({ error: \"hot_restart_intent_failed\" });\n      return;\n    }\n\n    res.status(202).json({\n      status: \"restart_requested\",\n      requestId,\n      mode: \"hot\",\n    });\n  });\n\n  router.get(\"/\", async (req, res) => {\n    const actorType = \"actor\" in req ? req.actor?.type : null;\n    const exposeFullDetails = shouldExposeFullHealthDetails(\n      actorType,\n      opts.deploymentMode,\n    );\n    const runtimeEnv = opts.runtimeEnv ?? process.env;\n    const startupRecovery = getStartupRecoveryState();","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/server/src/routes/health.ts#L202-L238","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check server logs for \"failed to coordinate hot restart request\" — the logged err names the underlying cause (DB vs filesystem).","Verify the dev-server supervisor status directory exists and is writable by the server process.","If the intent write failed on DB, check database health and connectivity, then retry the restart.","Ensure no concurrent restart requests are in flight; retry once the previous one resolves.","Fall back to a cold stop/start of the dev server if hot-restart coordination keeps failing."],"exampleFix":"// before: blind retry of the hot restart\nawait api.post('/api/dev-server/restart');\n// after: check writability and supervisor status first, then retry\nconst status = readPersistedDevServerStatus();\nif (!status) return coldRestart();\nawait api.post('/api/dev-server/restart'); // retry only after cause is fixed","handlingStrategy":"try-catch","validationCode":"// preflight before requesting a hot restart\nconst writable = fs.accessSync(devServerStatusDir, fs.constants.W_OK); // throws if not writable\nconst disk = checkDiskSpace(devServerStatusDir);\nif (disk.free < minRequiredBytes) throw new Error('insufficient disk for restart intent');","typeGuard":"function isHotRestartIntentFailed(body: unknown): body is { error: 'hot_restart_intent_failed' } {\n  return typeof body === 'object' && body !== null && (body as any).error === 'hot_restart_intent_failed';\n}","tryCatchPattern":"const res = await api.post('/api/dev-server/restart');\nif (res.status === 500 && isHotRestartIntentFailed(await res.json())) {\n  logger.error('hot restart coordination failed and was rolled back; falling back to cold restart');\n  return coldRestartServer();\n}","preventionTips":["Keep the dev-server supervisor status directory present and writable by the server process.","Monitor disk space where restart request/intent files are written.","Serialize restart requests; do not fire concurrent restarts.","Always fall back to a cold restart path when hot-restart coordination fails."],"tags":["restart","filesystem","http-500","hot-reload"],"backgroundTag":"internal-invariant-violation","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}