{"record":{"id":"0c018b20a727c791","repo":"NousResearch/hermes-agent","slug":"gateway-restart-failed","errorCode":null,"errorMessage":"Gateway restart failed.","messagePattern":"Gateway restart failed\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"apps/desktop/src/store/system-actions.ts","lineNumber":26,"sourceCode":"const POLL_ATTEMPTS = 18\nconst POLL_INTERVAL_MS = 1200\nconst POLL_TIMEOUT_S = 180\n\n// True while a gateway restart is in flight — drives the statusbar gateway\n// indicator (glyph spinner) so the restart shows up where users already look,\n// instead of a toast that vanishes or a generic \"Agents running\" counter.\nexport const $gatewayRestarting = atom(false)\n\n// Poll a backend action to completion (or a bounded window), throwing on a\n// non-zero exit so the caller can surface the failure.\nasync function awaitAction(started: ActionResponse): Promise<void> {\n  for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt += 1) {\n    await new Promise(resolve => window.setTimeout(resolve, POLL_INTERVAL_MS))\n    const status = await getActionStatus(started.name, POLL_TIMEOUT_S)\n\n    if (!status.running) {\n      if (status.exit_code != null && status.exit_code !== 0) {\n        throw new Error(translateNow('commandCenter.gatewayRestartFailed'))\n      }\n\n      return\n    }\n  }\n}\n\n// Restart the messaging gateway, surfacing progress in the statusbar gateway\n// indicator. Self-contained and never rejects, so every trigger — Cmd+K, the\n// messaging save/toggle toasts — gets identical feedback from a plain\n// `void runGatewayRestart()`, and a failure is the only thing that toasts.\nexport async function runGatewayRestart(): Promise<void> {\n  $gatewayRestarting.set(true)\n\n  try {\n    await awaitAction(await restartGateway())\n  } catch (err) {\n    notifyError(err, translateNow('commandCenter.gatewayRestartFailed'))","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/apps/desktop/src/store/system-actions.ts#L8-L44","documentation":"Thrown by awaitAction() inside the gateway-restart flow when the polled backend action (messaging gateway restart) finishes with a non-zero exit code. The action is started via a backend command, then polled with getActionStatus; a completed-but-failed process (exit_code != 0) surfaces as this localized 'Gateway restart failed.' error so the caller (runGatewayRestart, which never rejects) can toast the failure.","triggerScenarios":"runGatewayRestart() (Cmd+K command, or the messaging settings save/toggle path) starts a gateway restart action; the backend's restart script/process exits non-zero — port already in use, config parse error in gateway config, missing token, or the old gateway failing to stop.","commonSituations":"Gateway port conflict from a previous instance still bound, an invalid gateway platform credential edited in settings, or a config.yaml syntax error introduced by a settings save right before the restart.","solutions":["Inspect the backend gateway logs (~/.hermes/logs/gateway.log or the errors log) for the actual exit reason.","Check for a stale gateway process holding the port (ps / lsof) and kill it, then restart again.","Validate the gateway config/credentials just saved (settings -> messaging) — a bad token or YAML makes the restart script fail.","Retry via Settings -> Gateway restart after fixing the root cause; if the action status itself was unobservable, verify the backend action runner is alive."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await runGatewayRestart() // never rejects; check its toast\n} catch { /* not expected; kept for safety */ }\n// lower level:\ntry { await awaitAction(started) } catch (e) { surface(getActionLogTail(started.name)) }","preventionTips":["Before restarting, verify gateway config parses and the port is free.","Keep gateway logs open when changing messaging settings that trigger auto-restart.","Treat non-zero exit as actionable: read gateway.log, do not blind-retry."],"tags":["desktop","gateway","restart","process-exit"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}