Hermes Agent Not Working? Common Errors and How to Fix Them

Hermes Agent runs natively on Windows without needing WSL or Docker, but a handful of errors show up often enough that they’re worth having fixes for ahead of time. Most trace back to a small set of causes: PATH not refreshing after install, a shim or encoding mismatch, or a background service that didn’t start the way it was expected to. This guide walks through each one with the actual fix, not a generic “reinstall and try again.”

If you’re setting Hermes up for the first time, the Hermes Agent Windows Install guide covers the installer, editor setup, and terminal backend choices in detail.

Fix 1: “hermes: command not found” right after install

This is the single most common first error, and it isn’t actually a broken install.

The installer adds %LOCALAPPDATA%\hermes\bin to your User PATH, but any PowerShell window that was already open before the install finished doesn’t pick up that change automatically.

Open a new PowerShell window (or a new Windows Terminal tab) and try again. If it’s still not resolving, run the executable directly to confirm the install itself worked:

& "$env:LOCALAPPDATA\hermes\bin\hermes.exe"

You can confirm PATH picked it up correctly in a fresh window with:

Get-Command hermes
hermes --version

Fix 2: “WinError 193: %1 is not a valid Win32 application”

This error appears when running a tool that Hermes tries to invoke through a shebang script, and it bypassed the .cmd shim that Windows needs to actually execute it.

Hermes normally resolves commands through shutil.which(cmd, path=local_bin), which lets PATHEXT correctly pick up the .cmd variant of a tool. If a tool is instead being invoked through a hardcoded path, switch it to the .cmd version explicitly — for example, use npx.cmd rather than plain npx.

Fix 3: “The assignment expression is not valid” from the scriptblock installer

This shows up specifically when using the scriptblock form of the installer to pass parameters:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1))) -Branch main

The cause is a UTF-8 BOM picked up during the download of install.ps1. The plain irm | iex one-line form strips BOMs automatically, but [scriptblock]::Create((irm ...)) does not.

Re-run using the simple irm | iex form instead, or download the script manually and save it without a BOM:

[IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false))

Fix 4: Gateway won’t stay running after a restart

If the Hermes gateway keeps stopping instead of staying up in the background, start by checking its actual status rather than guessing:

hermes gateway status

This merges the state of the Scheduled Task entry, the Startup-folder shortcut (if one was used as a fallback), and the live process ID, so it will usually tell you exactly where the failure is.

If the Scheduled Task is registered but not actually running, group policy on the machine may be blocking ONLOGON triggers. Confirm this with:

schtasks /Query /TN HermesGateway /V /FO LIST

If group policy is the cause, uninstall the gateway and reinstall it with the Startup-folder fallback forced on, by setting the environment variable before running the install command:

$env:HERMES_GATEWAY_FORCE_STARTUP = "1"
hermes gateway install

Fix 5: /edit still does nothing after setting $env:EDITOR

Setting $env:EDITOR = "code --wait" only applies to the current PowerShell process. If /edit still opens nothing, the shell that’s running Hermes was likely opened before that variable was set.

Close and reopen the terminal, or set EDITOR permanently at the User scope through System Properties → Environment Variables instead of the process-scoped $env: command. Confirm it’s actually set in a fresh window with:

echo $env:EDITOR

Fix 6: Browser tool launches but tools time out

Hermes installs Chromium automatically the first time the browser tool is used. If that install failed silently — usually from a rate-limited GitHub request or a Playwright CDN hiccup — the browser tool will launch but every action inside it will time out.

Run the built-in diagnostic to confirm this is the cause:

hermes doctor

It will detect the missing Chromium install and print the exact npx playwright install chromium command needed to fix it.

Fix 7: agent-browser fails with a Node version error

This happens when an older Node install takes priority over the one Hermes actually needs. The installer provisions Node 26 at %LOCALAPPDATA%\hermes\node, but if a system-wide Node 18 install appears earlier in PATH, tools that depend on the newer version will fail with a version mismatch error.

Either move Hermes’s Node directory earlier in PATH, or remove the older system Node install if nothing else on the machine depends on it. Confirm which version is actually being picked up with:

node --version
where.exe node

The first result from where.exe node should point to %LOCALAPPDATA%\hermes\node, not a system-wide Node install.

Fix 8: Chinese, Japanese, or Arabic characters show as “?” in the CLI

This means the UTF-8 stdio shim that Hermes normally applies on Windows didn’t activate for that session.

Check whether it’s been explicitly disabled:

Get-ChildItem env:HERMES_DISABLE_WINDOWS_UTF8

If that variable is empty and the issue persists anyway, the console host itself may be the problem — very old cmd.exe sessions don’t support UTF-8 output at all. Switching to Windows Terminal resolves this in almost every case.

Fix 9: “Works on my other machine” encoding issues after git pull

If a Hermes config file or skill was edited on Windows using a non-UTF-8 editor — older versions of Notepad, or certain Chinese IME tools — the file may have been saved with a byte-order mark (BOM) without it being obvious.

Hermes tolerates a BOM on most config reads, but a BOM inside a folded YAML scalar (written as description: >) can silently break YAML parsing on another machine. Re-save the affected file as plain UTF-8 without a BOM using the same PowerShell command the installer itself relies on for BOM-free writes:

[IO.File]::WriteAllText($path, (Get-Content $path -Raw), (New-Object Text.UTF8Encoding $false))

What Causes Most Hermes Agent Errors on Windows

Looking across all nine fixes above, the underlying causes repeat more than the errors themselves do:

• PATH not refreshed. Several errors, including the most common “command not found” issue, come down to a terminal window that was open before PATH was updated.
• Encoding mismatches. BOM characters picked up during download or from certain editors account for multiple separate failure modes, from installer errors to broken YAML.
• Version conflicts. An older system-wide tool (usually Node) taking priority over the one Hermes installed causes several tool-specific errors.
• Background service state. Gateway issues are almost always a Scheduled Task or Startup-folder configuration problem rather than something wrong with Hermes itself.

Frequently Asked Questions