Hermes Desktop Won't Open After an Update

Steps

1. 1

   Protect the Hermes home before changing anything

   Do not uninstall everything or delete ~/.hermes. That directory can hold profiles, sessions, memory, skills, cron jobs, auth, and config. If the CLI still starts, run hermes update --backup; otherwise copy the Hermes home before reinstalling. Follow the backup guide when the profile is expensive to reconstruct.

2. 2

   Classify the visible failure before changing files

   Blank white/black content with the window chrome visible points to the Desktop renderer or damaged app assets. A window stuck on startup points to the local hermes serve backend, port 9119, PATH, or a stale process. Desktop opening but Chat failing points to the selected profile/connection, provider, dashboard authentication, or /api/ws. Bots missing after an update can mean the wrong owning backend or a changed filter/layout—not deleted profiles. Record which branch you have before reinstalling anything.

3. 3

   Close Desktop and stop stale child processes

   Quit every Desktop window. Stop the local gateway with hermes gateway stop if it uses the same install, exit open Hermes REPLs, and close old updater or backend processes. On Windows this matters because running hermes.exe, Python, or native-extension files can lock the venv and make a dependency refresh stop halfway.

4. 4

   Prove whether the shared Hermes runtime still works

   Run hermes --version, hermes doctor, and hermes chat -q "reply ok". If these pass, your provider, profile, and core runtime are available; focus on Desktop build or startup. If they fail, use the layer-by-layer Hermes troubleshooting guide before rebuilding the GUI.

5. 5

   Use Web UI as a recovery checkpoint

   Run hermes dashboard and open http://127.0.0.1:9119. A working Hermes dashboard confirms that sessions and profile state can still be read, but it does not repair Desktop by itself. Stop it before relaunching Desktop if both try to own the same backend port.

6. 6

   Read the updater logs before retrying

   Inspect ~/.hermes/logs/update.log and ~/.hermes/logs/bootstrap-installer.log. Look for a real updater still running, an in-progress marker, Node/npm engine mismatch, PATH failure, locked Windows executable, failed native dependency, or incomplete Desktop build. Do not remove ~/.hermes/.hermes-update-in-progress unless no updater process is active.

7. 7

   Preview and complete the supported update

   Run hermes update --check, then hermes update. Read any partial-update message literally: core Python may be current while Desktop assets are not. If Node/npm failed, compare node --version and npm --version with the current source requirements instead of bypassing engine checks or using blanket sudo. The hanging-update recovery guide covers mixed dependency state.

8. 8

   Rebuild and relaunch the native app

   Run hermes desktop. The command installs the Desktop workspace dependencies, builds the current operating system's unpacked Electron app, and launches it. Use hermes desktop --force-build when a stale content stamp or incomplete build is the suspected cause. Use --skip-build only when a verified unpacked app already exists.

9. 9

   Apply the operating-system branch

   On Windows, close every process using the Hermes venv and retry the transactional update before forcing anything. On macOS, check reduced PATH when app-launched subprocesses cannot find git, ssh, bash, node, or npm. On Linux, verify Node/npm, executable permissions, and whether the app was started from the same account and environment as the working CLI.

10. 10

    Reconnect the intended local or remote backend

    If Desktop opens but Chat disconnects, confirm the profile's connection mode. Local mode starts its own hermes serve backend; remote mode points to a protected serve-compatible backend, normally on port 9119—not the OpenAI-compatible API on 8642. Use the remote Desktop backend guide for HTTP versus WebSocket failures.

11. 11

    Verify one real Desktop workflow

    Open the intended profile, send one message, and verify one artifact, file, terminal action, or tool result. If you restarted a gateway, also test the exact Telegram or Discord destination. Choose FlyHermes managed hosting when the real requirement is browser/mobile access and uptime without owning Desktop, provider, update, backup, and gateway maintenance.

12. 12

    Treat session-storage FATAL errors as backend state failures

    If Desktop opens but a prompt fails with session storage unavailable, do not reinstall the UI or delete SQLite files. Use the state.db troubleshooting workflow: align versions, fully quit Desktop, restart the gateway once, inspect session stats, and preserve WAL/SHM sidecars for recovery.

Pro Tips

• 💡Treat a working CLI or dashboard as evidence that state survived, not as proof the native app is repaired.
• 💡Use hermes desktop --force-build for a suspected stale or incomplete Desktop artifact; do not begin with a full data-destructive uninstall.
• 💡On Windows, do not use --force-venv until you have verified that reported venv holders are false positives.
• 💡If only the GUI needs removal, hermes uninstall --gui preserves the agent, config, and chats; avoid hermes uninstall --full during recovery.
• 💡After recovery, follow the session handoff checklist before a planned restart of important long-running work.
• 💡After a v0.21-era layout change, verify the selected backend and profile roster before recreating a missing Bot.
• 💡A four-day blank screen is not a reason to delete the Hermes home: prove the CLI and dashboard state first, then rebuild only the Desktop layer.
• 💡Capture the exact symptom and timestamp so Desktop, backend, update, and provider logs can be compared from the same launch attempt.

Troubleshooting

FAQ

Related setup and cost guides