Hermes Agent on Windows: command not found and other fixes

What you see

• hermes isn't recognised right after installing.
• Chinese, Japanese or Arabic text shows up as ?, or a UnicodeEncodeError mentions charmap.
• WinError 193: %1 is not a valid Win32 application when a tool or hook runs.
• /edit or Ctrl-X Ctrl-E returns an empty buffer or does nothing.
• The gateway doesn't come back after you log in again, or keeps disconnecting under WSL2.

Likely causes

Hermes runs natively on Windows 10 and 11, and the native install keeps its data under %LOCALAPPDATA%\hermes. WSL2 is a separate install with its own ~/.hermes, and the two don't share state. Most native problems come from the gaps between Windows and POSIX: the installer adds Hermes to your User PATH, which existing terminals don't see; old consoles don't handle UTF-8; Windows has no shebang support, so a bare script can't be launched directly; and the gateway runs as a Scheduled Task at logon, which group policy can block. Under WSL2, the usual problem is systemd being missing or unreliable.

Check this first

• Which install you're using: native PowerShell or WSL2. Settings and keys in one don't apply to the other.
• In a new PowerShell window, Get-Command hermes should point under AppData\Local\hermes\bin, and hermes --version should answer.
• hermes gateway status combines the Scheduled Task, any Startup-folder launcher and the live process ID.
• Terminal commands run through Git Bash, so make sure Git for Windows (with Bash) is installed. The docs note that MinGit is not a replacement.
• hermes doctor and hermes pm doctor cover most dependency and browser-tool problems.

Fix

Command not found: open a new PowerShell window rather than editing $env:PATH by hand. Until then, you can run & "$env:LOCALAPPDATA\hermes\bin\hermes.exe". Garbled characters: make sure HERMES_DISABLE_WINDOWS_UTF8 isn't set, and use Windows Terminal instead of a very old cmd.exe. Editor problems: set EDITOR at User scope, not just in the current shell. For VS Code, use code --wait, because without --wait Hermes gets an empty buffer back.

• WinError 193: call the .cmd form of a tool (for example npx.cmd) instead of a hardcoded path to a script. For shell hooks, start the command with the script file itself so Hermes can choose the interpreter, such as Git Bash for .sh.
• Installer error 'The assignment expression is not valid': the downloaded script picked up a byte-order mark. Use the plain irm | iex form instead.
• Gateway not starting at login: reinstall the task with hermes gateway install. If the task is registered but never runs, check why with schtasks /Query /TN Hermes_Gateway /V /FO LIST. Group policy can block logon triggers.
• WSL2 gateway dropping: run it in the foreground with hermes gateway run, inside tmux so it outlives the terminal, or enable systemd in /etc/wsl.conf with [boot] and systemd=true, then run wsl --shutdown and reopen the terminal.

If it still fails

If YAML in a config file or skill suddenly stops parsing after you edited it on Windows, re-save the file as plain UTF-8 without a byte-order mark. Some editors add one, and it breaks folded YAML values. If you're running a model server on Windows while Hermes runs in WSL2, localhost won't reach it under WSL's default networking. Enable mirrored networking or use the host's address.

To remove and reinstall cleanly, preview first with hermes uninstall --dry-run. Don't delete %LOCALAPPDATA%\hermes by hand to repair the app: that folder also holds your configuration, credentials and sessions. Make a backup with hermes backup before any data-removal option.

Related guides

• Hermes Agent install or update failed
• Hermes Agent bot not responding in your chat app
• Hermes Agent terminal can't find files or programs
• Where Hermes Agent runs: host vs work environment

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher