Hermes

Hermes couldn't start: the background gateway didn't come up

Last checked

The error

Hermes couldn't start
Hermes' background service didn't come up. Try one of the recovery steps below. Nothing here deletes your chats or settings.

[Retry]  [Repair install]  [Use local gateway]  [Gateway settings]  [Open logs]

Current wording from the Hermes Desktop boot screen (apps/desktop/src/i18n/en_boot.ts). Builds from mid-2026 said "The background gateway didn't come up. Try one of the recovery steps below" (issue #73149).

Hermes Desktop waited for its local gateway or backend to report ready and gave up. Nothing is deleted. Click Retry once; if that fails, quit every Hermes process, check that ports 8642 and 9119 are free, run hermes doctor --fix, then use Repair install. The Open logs button shows the real cause, which Desktop also summarises under the heading when it can.

Why it happens

Desktop starts a background service (the gateway and its backend) and waits for it to answer. When it doesn't, Desktop shows this full-screen boot failure instead of the chat window.

  1. The background service stopped right after starting, usually a Python error from a half-finished update. See the backend-exited page.
  2. It didn't answer in time, for example a slow first boot or a stale process from an earlier run holding the port.
  3. Another program is using the port Hermes needs (the gateway API defaults to 8642, the dashboard to 9119).
  4. Hermes couldn't write to its data folder, the disk is full, or part of the installation is missing.
  5. A Windows regression in July 2026 showed this screen on every cold start until Retry was clicked (issue #73149, closed).

The fix

  1. 1 Click Retry once. If it always works on the second try, update Hermes.
  2. 2 Quit Hermes Desktop and make sure no hermes processes remain, then relaunch.
  3. 3 Check the ports: lsof -i :8642 and lsof -i :9119 (on Windows, netstat -ano | findstr 8642). Stop whatever holds them.
  4. 4 Run hermes doctor --fix in a terminal and fix anything it cannot repair.
  5. 5 Click Repair install. It re-runs the installer and can take a few minutes; chats and settings in ~/.hermes are kept.
hermes doctor --fix

Still failing?

  • Click Open logs and read the last lines of desktop.log before the failure.
  • If the screen names "Timed out connecting to Hermes backend", follow the backend timeout page.
  • Click Use local gateway to get into the app and fix settings from inside.

Related errors

Full guideHermes Agent Not Working? 14 Errors and Their Exact Fixes

Hit a different error?

Paste any agent error and get the cause and fix in seconds.

Open the decoder

Frequently asked questions

Does Repair install delete my chats?

No. The boot screen says so, and your sessions, config and keys live in the Hermes data folder, which the installer leaves in place.

Is the gateway the same as the backend?

Desktop talks to a local background service that runs the gateway. Older builds called it the background gateway; current builds call it the background service. The fix is the same.

Why does Retry usually work?

Many failures are timing: a slow first start or a process from the last session still shutting down. If Retry is needed on every launch, update, because that was a known regression.

Stop firefighting agent errors

Decoding errors one at a time is the manual version of what BetterClaw automates. Run your agents on a no-code AI agent platform with managed models, retries and config validation built in.

Deploy Your Agent — Start FreeBook a Demo

Free plan available · Pro $49/mo · BYOK · 7-day free trial