# Hermes Agent on Windows: command not found and other fixes > Work through the documented Windows pitfalls for native installs and WSL2, from PATH and encoding to editors, shell scripts and the login-time gateway task. Canonical: https://hermeswatcher.com/troubleshoot/windows-specific-problems Section: Troubleshooting ยท Running & deploying Last reviewed: Oct 20, 2026 Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources. ## 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](https://hermeswatcher.com/troubleshoot/install-or-update-failed.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent terminal can't find files or programs](https://hermeswatcher.com/troubleshoot/terminal-cannot-find-files-or-programs.md) - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) ## Related tools - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Terminal backends: choose where the agent's commands run](https://hermeswatcher.com/tools/terminal-backends.md) ## Sources - [Windows (Native) Guide (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native) - [Windows (WSL2) Guide (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/windows-wsl-quickstart) - [FAQ: WSL gateway and installation issues (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [Event Hooks: shell hooks on Windows (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks) --- HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt