hermes update failed: the four errors and their fixes
Hermes Agent's update failing on a Linux server: the stable source channel timeout, gateways not restarted, the update lock and the Matrix build, with fixes.
Four messages account for most failed or half-finished hermes update runs on a Linux server, as of November 2026 (latest release v0.23.1):
- “Could not resolve the stable source channel … No update was applied.” An older updater gave up on a slow git check, common with Ubuntu 24.04’s git. Run
cd ~/.hermes/hermes-agent && git fetch origin --tags && hermes updateonce. - “A previous `hermes update` pulled new code but did not restart running gateways.” Check
hermes gateway status, thenhermes gateway restart. The warning can outlive the problem. - “Another Hermes update is already running” Another update holds the lock. Watch
hermes logsand run the update again once it ends. - The Matrix extra failing to build (python-olm, a missing
clang++, or CMake 4). Install the build tools and runhermes pm install --extra matrix, or drop it withhermes pm install --without matrix.
First, which Hermes you are on
The installer and hermes update follow the stable channel by default: the newest published release, then release to release. The installer’s help puts it as “stable (default): the latest published release, then release to release. main: every commit.” v0.23.1 was published on November 10, 2026. hermes --version shows what you have, and hermes update --check compares the checkout with the channel’s target without installing anything or restarting gateways. On the main channel the version carries a commit count past the last release, such as v0.21.7+179. hermes update --set-channel main switches for good, and hermes update --channel main uses main for one run without saving the choice. Nous’s updating page covers both. A version that has not moved since October while new releases have come out can mean the first failure below.
“Could not resolve the stable source channel”
The full output looks like this, with two commit hashes in the middle:
→ Update channel: stable
✗ Could not resolve the stable source channel: Command '['git', 'merge-base', '--is-ancestor', '<commit>', '<commit>']' timed out after 10 seconds. No update was applied.CopiedNothing was changed, and the install still works. Before it fetches anything, the updater asks git whether one commit comes before another, and gives that question 10 seconds. The installer’s checkout is a blobless partial clone, and on that kind of clone the git that ships with Ubuntu 24.04, 2.43, takes longer than that. A Hermes maintainer measured it at “7–12 s of CPU”, and another report on Ubuntu 24.04 with git 2.43.0 timed the check at 12.1 seconds.
The fix landed on main on October 15, 2026. A check that cannot answer in time now falls back to GitHub’s own comparison of the two commits, and v0.23.1’s code still does this. The catch is that hermes update runs the updater you already have, so an install from before mid-October cannot update its way out. The maintainer’s one-time unblock:
cd ~/.hermes/hermes-agent && git fetch origin --tags && hermes updateCopiedIf that still times out, the check can be made fast. With a commit-graph file in the checkout, the same check took 3 milliseconds instead of 12 seconds in the report above, and the graph took about a second to write. v0.23.1 writes the graph itself during hermes update when there is none or it is more than a day old, with this command, which you can run yourself in the checkout before updating:
cd ~/.hermes/hermes-agent
git commit-graph write --reachable --split --no-changed-paths
hermes updateCopiedLeave out --no-changed-paths and git writes extra path data instead. Hermes’s own code avoids that because, on this kind of clone, writing it can make git download file trees one commit at a time. Re-running the installer is the other way out: v0.23.1’s release notes give “re-run the installer one-liner” as the alternative to hermes update, and the one-liner is curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. The same message with a different reason after the colon, such as “No published stable release could be verified”, comes from the step that looks up the release itself rather than this git check, so the commands above are not aimed at it.
“pulled new code but did not restart running gateways”
Hermes prints this on every later start of the command line until it believes the gateways are current:
⚠ A previous `hermes update` pulled new code but did not restart running gateways.
Gateways may still be serving pre-update modules (mixed sys.modules).
Run `hermes update` or `hermes gateway restart`.CopiedIt means the code on disk is newer than the code a running gateway loaded. An update does not cut off a gateway in the middle of work. It waits for the gateway to be idle, printing a line every 30 seconds while it drains, and the wait has a limit. If the limit runs out, the gateway keeps its restart pending and restarts at its next idle moment. So a gateway that is always busy, with long chats, cron jobs or background tasks, can stay on the old code for a while after the update has finished.
To act on it: hermes gateway status lists the gateway services and shows whether one is still draining. If it is not, and the service started before the update finished, hermes gateway restart restarts it (add --all to restart every profile’s gateway). With the gateway as a systemd user service, systemctl --user status hermes-gateway shows when it last started, which tells you whether it ever picked up the update. Running hermes update --force skips the wait entirely, and Nous’s page is clear about the cost: each gateway stops at once and interrupts its running chat turns, cron jobs and background delegations.
The warning is not always true. In an open issue, users on Linux with the gateway under systemd --user report it staying “hours later, on a fleet that is in fact fully current”, and hermes gateway restart not clearing it. If the gateway’s start time is after the update and it is answering, the old code is gone and the warning can be ignored. As of v0.23.1 the three lines above are unchanged.
“Another Hermes update is already running”
✗ Another Hermes update is already running (started 52s ago, process 1916).
Running two at once would corrupt the install. Wait for it to finish
(watch `hermes logs`), or close the Desktop/dashboard window that
started it, then run `hermes update` again.CopiedOne update holds a lock on the install, and a second is refused until it ends. On a server the first is usually still alive: an update started from another SSH session, from the dashboard, or one waiting for a busy gateway to go idle, as in the section above. Even a second hermes update --force is refused while the first one waits. hermes logs -f follows what it is doing. To see what the named process actually is, ps -p 1916 -o etime,args (with your process number) prints its age and command line.
An update whose process has died does not normally leave the lock behind. Hermes checks whether the recorded process is alive and is the same process that took the lock, and reclaims the lock if not. The exception is a variant that ends “its owner exited but a process it started still holds the checkout”. The updater exited, but a process it started is still working in the checkout. Waiting for that process to end clears it. There is one known way to be refused wrongly: an open report from a Linux server with systemd user services has the lock surviving a successful update, with its process number later reused by hermes dashboard. If ps shows the named process is a gateway or the dashboard rather than an update, that is this bug. The reporter removed the lock file by hand. Hermes has no documented command for it.
The Matrix extra stops the update
If the gateway talks to Matrix, the update also has to build the matrix extra’s encryption library, python-olm, from source. Hermes’s pinned Python 3.14 has no ready-made package for it, and on Linux the extra still requires mautrix[encryption] at v0.23.1 even when encryption is off. In an open issue that collects the reports, and a second one from Ubuntu 24.04 servers, it fails in three ways:
error: [Errno 2] No such file or directory: 'clang++'. The pinned Python records clang as its compiler, and a stock Debian or Ubuntu host has only gcc and g++.- CMake 4, which, in the issue’s words, “rejects libolm’s
cmake_minimum_required”. - A missing
libolmlibrary, which Nous’s Matrix page installs withsudo apt install libolm-devon Debian and Ubuntu.
Hermes’s summary of the failure can hide the cause. Reports show extra 'matrix' unavailable: venv: uv sync exited 1: Apache Software License, with the real compiler error higher up in the output. In the reports the failure aborted the whole update. v0.23.1’s code handles it in two ways. When clang is missing but gcc and g++ are present, Hermes uses gcc and g++, unless you have set CC or CXX yourself. And a Matrix extra carried over from an older install that no longer builds is left out rather than failing everything: the update installs the rest and prints “Left the optional 'matrix' extra out of this update” with the command that adds it back. A failure that looks temporary, such as a download, still stops the update before anything is replaced, and the next hermes update tries again. An extra you asked for yourself still fails loudly.
The way back, from Nous’s package-management page: fix the build, then add the extra again.
hermes pm install --extra matrixCopiedOn a host with CMake 4, reporters got past the libolm check by setting CMAKE_POLICY_VERSION_MINIMUM=3.5, together with CC=gcc CXX=g++, for the command that rebuilds. That is a workaround from the reports, not a documented step. If the server does not need Matrix, hermes pm install --without matrix drops the extra and records the choice, so updates stop trying to build it. The Matrix connection goes with it. With the extra installed but encryption’s pieces missing, the Matrix page says the adapter falls back to an unencrypted client and logs a warning.
When an update leaves things worse
If the checkout itself is damaged, Nous’s answer is the installer again: it moves the old checkout aside as hermes-agent.broken-<timestamp>, deletes nothing, and clones fresh, keeping your settings, keys and sessions in ~/.hermes. hermes doctor afterwards reports anything still missing or broken. How an install is laid out, and what an update touches, is in the guide to installing Hermes on a Linux server. Whether updating it at all should be your job is the subject of where to host Hermes Agent.