When the Hermes Update Command Hangs: What Fixed It

If hermes update hangs, Desktop loops on Retry Update, Node dependencies fail, Docker refuses the command, or a gateway stops after a restart, treat it like an operations incident. Preserve state first, then isolate whether the failure is install method, process locks, PATH, git, Python, Node/npm, Docker/WSL, or a stale long-running service.

Why this page exists#

A fresh Discord scrape on August 2 captured 985 threads and 5,284 messages, current through August 1. In just the July 30–August 1 support window, at least a dozen separate threads involved update hangs, Windows/WSL locks, Desktop retry loops, npm engine failures, installers, or mixed dependency state. This is not a generic install keyword guess: it is a concentrated current support problem, and the existing update pages already own the intent.

August 2026: the three update failures users are hitting now#

1. Node/npm engine mismatch leaves a partial update#

Current Hermes refreshes Python and several Node workspaces in one update. If npm prints EBADENGINE and Hermes says the update is partially complete, code and Python dependencies may already be current while Desktop, dashboard, or TUI dependencies are not.

node --version
npm --version
cd ~/.hermes/hermes-agent
node -p "require('./package.json').engines"

Trust the checked-out package.json and the error's Required/Actual lines, because engine constraints can change between releases. Prefer a supported LTS Node/npm pair. Do not bypass engine-strict, and do not turn a version mismatch into a root-owned npm cache by reflexively running global installs with sudo.

2. Desktop Retry Update can invoke the old updater once more#

If the Desktop updater loops on an in-progress marker, close every Hermes Desktop window and verify no updater is still running. Then inspect:

tail -n 100 ~/.hermes/logs/bootstrap-installer.log
tail -n 100 ~/.hermes/logs/update.log

Only remove ~/.hermes/.hermes-update-in-progress when you have confirmed the update process is gone. Run the installed terminal/bootstrap updater to land the fixed updater, then reopen Desktop. On Windows, also stop the gateway and exit open Hermes REPLs so hermes.exe and venv native files are not locked.

3. Restore local changes is about source edits, not memory#

hermes update auto-stashes tracked and untracked changes in the Hermes source checkout before pulling. The restore prompt does not refer to MEMORY.md, sessions, or normal profile state. Choose restore only when you recognize intentional source edits, then inspect git status and git diff. If you decline, the stash remains preserved for manual recovery.

For the concise end-to-end workflow, use How to Update Hermes Agent Safely. For version-specific upstream context, check the official release history.

June 2026 update: v0.15.2 and current main fixes#

The latest Hermes GitHub work turns several common install/update problems into clearer recovery paths instead of mystery crashes. Check these before deleting state or rewriting config:

• Docker config migrations now run during container boot. Update the image and restart before hand-editing an older config.yaml.
• Unsupported arbitrary Docker users fail with clearer guidance. Avoid forcing docker run --user <random-uid> when the image cannot own the Hermes home tree.
• UID remap/chown handling was repaired. If mounted build trees or ~/.hermes became unwritable after an update, pull the latest image and inspect ownership before rebuilding from scratch.
• Python 3.14 is capped out for now. If install breaks on bleeding-edge Python, pin Hermes to a supported interpreter and rerun hermes doctor.
• Desktop managed clone updates are safer. The update flow no longer lets stash/restore clobber Desktop-managed source trees in the same way, but source installs should still check git status before and after hermes update.
• MCP discovery now expands ${ENV} in header auth probes. Header-auth MCP failures can be a missing container env var or an old Hermes version, not necessarily a broken MCP server.

For container-specific failures, use the dedicated Hermes Docker troubleshooting checklist. For a higher-level release summary, read what changed in Hermes Agent v0.15. For Desktop remote-backend setups, use the Hermes Desktop remote backend guide.

First: protect Hermes state#

Before reinstalling or deleting anything, remember that ~/.hermes can contain:

• config.yaml
• .env secrets
• sessions and memory
• skills and plugins
• cron jobs
• OAuth/provider auth
• the source checkout if installed from git

A safe pre-update backup pattern is:

cd ~/.hermes/hermes-agent
mkdir -p /tmp/hermes-update-backups
stamp=$(date +%Y%m%d-%H%M%S)
git status --short > /tmp/hermes-update-backups/status-$stamp.txt
git diff > /tmp/hermes-update-backups/working-tree-$stamp.diff
git diff --cached > /tmp/hermes-update-backups/index-$stamp.diff
git stash push -u -m "pre-update-$stamp"

Fix macOS reduced PATH problems#

On macOS, Hermes may be launched by a gateway, LaunchAgent, cron, or app wrapper with a reduced PATH. That can make child processes fail with git, ssh, bash, npm, or launchctl missing even when your interactive shell can find them.

Run quick checks:

which hermes
which git
which ssh
which bash
hermes --version

Then retry with a full PATH:

PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes update

If the update command itself is still stuck, update the source checkout manually.

Manual source update fallback#

cd ~/.hermes/hermes-agent
/usr/bin/git fetch --tags origin
/usr/bin/git checkout main
/usr/bin/git pull --ff-only origin main
hermes config migrate
hermes doctor

If package metadata is stale after a source update, use the repo venv, which is commonly venv/:

cd ~/.hermes/hermes-agent
venv/bin/python -m ensurepip --upgrade
venv/bin/python -m pip install -e .
hermes --version
venv/bin/python - <<'PY'
import importlib.metadata
print(importlib.metadata.version('hermes-agent'))
PY

Docker and WSL are separate layers#

Do not confuse these three paths:

• Docker Compose runs Hermes as a long-lived service.
• The Docker terminal backend lets Hermes execute shell commands inside containers.
• WSL is the Linux environment Windows users may use to run Hermes.

If file or terminal tools fail with Docker startup errors such as exit 127, switch the terminal backend to local to isolate the problem:

hermes config set terminal.backend local
hermes doctor

Then return to Docker Compose setup or Docker terminal backend configuration after the local CLI works.

Gateway restart failures#

A stale gateway can survive code/config changes and keep old modules in memory. Symptoms include Telegram or Discord not replying, import/signature errors, or status files saying connected while real messages fail.

Use service-level restart checks:

hermes gateway status
hermes gateway restart
hermes gateway status

For macOS launchd, a harder restart may be needed:

/bin/launchctl kickstart -k gui/$(id -u)/ai.hermes.gateway
sleep 5
cat ~/.hermes/gateway_state.json

Then verify end-to-end with the actual channel, for example the Telegram setup guide, not only a green process state.

Provider and fallback failures can look like install failures#

Sometimes the binary is fine but the agent fails because a provider is exhausted, a model route changed, or an auxiliary task hit a rate limit. If hermes doctor passes but jobs fail during compression, session search, memory, or delegation, use the provider fallback guide and the provider cost guide.

Self-hosting vs managed path#

Self-hosting Hermes is powerful, but the full stack includes install, updates, Python packaging, provider keys, gateway services, Docker/WSL, dashboards, logs, and uptime. If you want the agent outcome without owning those layers, FlyHermes is the hosted alternative.

FAQ#

Why does hermes update hang on macOS?#

Common causes are reduced PATH, missing git or ssh in the subprocess environment, dependency installation, stale source checkout state, or gateway processes that need a full restart.

Should I delete ~/.hermes and reinstall?#

No, not as the first fix. Back up state and repair the checkout or venv first. ~/.hermes may contain memory, skills, cron jobs, sessions, and credentials.

Why does Telegram break after an update?#

The gateway may still be running old code against newer files, or it may have restarted with a reduced PATH or wrong profile. Restart the service process and verify the actual chat, not only the status file.

Gateway restart after updates#

After an update, do not trust an old long-running gateway process. Restart it with a full PATH, inspect current agent.log, and run the gateway troubleshooting checklist until a real Telegram or Discord message receives a reply. This catches stale module graphs, launchd PATH problems, and provider/config drift before users experience a silent bot.