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.

Historical support patterns#

An August 2 community archive recorded update hangs, Windows/WSL locks, Desktop retry loops and dependency failures. Those observations are historical support reports, not evidence of current failure frequency. Use the current official update path and the exact error from your installed build before applying an older workaround.

Source-install failure patterns to distinguish#

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.

Identify the update owner before repairing anything#

The official updating guide distinguishes managed source, bundled Desktop, Store, Docker, Nix and Termux installations. A source checkout uses hermes update; Windows Store packages use Store updates, Windows sideload MSIX uses the Desktop/App Installer flow, and macOS bundles use the Desktop update control. Docker requires pulling the chosen image and recreating the container with the same data mount. Do not run source-update commands inside a package-owned application.

Desktop package versions and backend agent versions need not match. Record both identities and the client commit using the Desktop version checklist. A failed availability check means availability is unknown, not that no update exists. A successful download does not prove the new application relaunched.

For supported source installs, preview before applying:

hermes update --check
hermes update --plan

These are preview commands, not permission to change the installation. Check hermes update --help on an older build before using the fleet-plan option. Review every eligible target before a multi-backend Desktop update; the current documented action can update connected and other registered backends before the client.

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

For an admitted source installation, current documentation describes automatic pre-update state snapshots, but snapshot failure can warn and continue. Read the receipt instead of assuming backup succeeded. Use hermes update --backup when intentionally applying a source update with a full pre-update backup, and verify the archive exists before relying on it.

A source git diff or stash is not a backup of sessions, credentials or mounted container state. Back up the actual owning Hermes home securely; archives may contain secrets. Preserve the old build identity and consult the official rollback instructions before downgrading shared data.

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 it still fails, preserve the exact error and follow the source-maintenance guidance below; do not reset the checkout blindly.

Repair source dependencies without replacing the wrong environment#

Current Hermes uses its package manager to prepare dependencies. The official guide distinguishes application updates from dependency management: hermes pm update is a maintainer pin-update operation, not a substitute for the application updater. For damaged dependencies, follow the documented PM repair workflow rather than installing into an arbitrary system Python or copying an old venv command.

Retain the first failed phase and exact error from the active profile's logs/update.log. If a source-built Desktop rebuild fails, current stage-and-swap behavior keeps the previous app launchable. The documented rebuild retry is hermes desktop --build-only --force-build, or a subsequent source update once the underlying error is resolved. This source-build recovery is not the correct update mechanism for a Store or signed bundled app.

Before any manual source maintenance, record git status and preserve intentional local changes. Do not use a blind checkout/reset as a generic repair. Follow the official manual maintenance and rollback instructions for your installed distribution.

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, inspect Docker availability and the configured backend first. Switching to local removes the container execution boundary: do this only intentionally on a trusted test profile, with no untrusted task running. It is not a generic sandbox repair:

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 a confirmed macOS launchd-managed default gateway, a forced restart is a last resort after inspecting active work and allowing normal draining. It can interrupt running jobs; verify the service identity before using:

/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.

When the update finishes but Desktop is still blank#

A completed core update can coexist with incomplete Desktop assets. If hermes --version, hermes doctor, and a CLI chat pass while the native window stays blank or stuck, use the Desktop after-update recovery decision tree. Preserve state, inspect the same-attempt logs, repair Node/npm or process locks, and rebuild Desktop with --force-build only after isolating the client layer.

Verify the running build, not just update completion#

After the updater exits, reopen the intended application and record its client commit, backend identity and selected profile. Do not require the Desktop package number to equal the agent version. Compare hermes --version only with the runtime reached by that same shell, and inspect the running container separately if Desktop uses Docker.

A manually launched hermes serve or hermes dashboard process may still need its owner to restart it; the official update guide separates those processes from service-managed messaging gateways. Preserve HERMES_HOME, restart only the intended service during maintenance, and verify one harmless prompt plus any required channel delivery. A stale HERMES_WEB_DIST can also serve old browser assets even when core code advanced. The Dashboard guide covers that separate browser surface.