Hermes Agent

Hermes Agent: Fixes

This is page 6 of 8 in the Hermes Agent guide. It covers the problems people hit most often with Hermes, drawn from its FAQ, its Windows guide, and its GitHub issues, each in the order symptom, likely cause, and fix.

These fixes match the docs as checked on 14 November 2026. Several of them use a terminal, which means PowerShell on Windows and Terminal on a Mac, opened as your everyday account.

Common problems

Stop it right now

Symptom: Hermes is doing something you did not ask for, or a job is running away.

Likely cause: a misread prompt, a confusing page, or a prompt injection.

Fix: use the first of these that fits.

Closing a window is not a reliable stop. Hermes's CLI docs say that closing a terminal chat, or pressing Ctrl+D, leaves the current job running in the gateway. The desktop app's Stop button ends only the current step; type /stop to end sub-agents too. Quitting the desktop app leaves work running in the background gateway, so use hermes gateway stop for that. On a Mac with only the desktop app, this guide could not confirm that the hermes command works in Terminal, so restart the computer if nothing else stops it.

What you should see no new steps appear in the chat, and hermes gateway status no longer shows a running gateway after hermes gateway stop. If it already changed something, read After it does something wrong.

The install fails

Symptom: the desktop app will not install or keeps repairing itself, or the command install stops with an error.

Likely cause: one of four known causes.

Fix: check your Windows version first. Then try the Microsoft Store version, or the PowerShell command from page 2. Do not turn off Smart App Control or Defender as a whole to get past a block. Hermes's Windows guide, writing about a different block, also says not to disable Windows security controls to work around it. On a Mac, do not use sudo with the installer, since the FAQ says it installs into your own account's folders and a sudo install causes "permission denied" errors.

What you should see Hermes in your Start menu or Applications folder, or a finished command install with no error.

Typing hermes says it is not found

Symptom: after the command install, the terminal says it does not know hermes.

Likely cause: the terminal was open before the installer added Hermes to your program folders.

Fix: close the terminal and open a new one. On Windows, the Windows guide says Get-Command hermes should then show a path ending in hermes\bin\hermes.exe. On a Mac, type source ~/.zshrc, and if that still fails, the FAQ says to check that ~/.local/bin/hermes exists.

What you should see hermes --version prints a version number.

The model says the key is wrong

Symptom: Hermes answers with an error about the key, or with "Error 400" on the first message.

Likely cause: the key is missing, mistyped, expired, or meant for a different provider. The FAQ says an Error 400 on the first run is usually a model name that does not exist on your provider.

Fix: open .env and check that the line reads GEMINI_API_KEY= followed by your whole key, with no spaces or quote marks. The FAQ says an OpenAI key will not work with OpenRouter and the other way around, so check that the key matches the provider. In a terminal, hermes config show shows what Hermes loaded, and hermes model lets you choose the provider and model again from a list.

What you should see you type "hello" and Hermes answers.

The model stops answering or says to slow down

Symptom: replies stop, or you see a "429" or a rate limit message.

Likely cause: you hit your provider's rate limit. A free Gemini key runs out fastest, because Hermes may call the model several times for each message.

Fix: wait and try again. The desktop app's error card shows Limit resets at with a time when the provider says when the limit lifts, and its Retry button can try again then. If it keeps happening, switch to another model with the error card's Switch provider button, or see Pick your model and budget.

What you should see Hermes answers again after the reset time.

It says the model service is not reachable

Symptom: replies fail with a message that the model cannot be reached, such as "The AI model service isn't reachable right now." in a phone chat.

Likely cause: the FAQ says nothing accepted the connection. With a local model, the model server is usually not running, and with a cloud model, your internet connection or the provider is down.

Fix: start your local model server again, or check your connection, then type /retry. For a local model, also check the address that hermes model saved. The FAQ suggests hermes doctor if it keeps happening.

What you should see the next reply arrives normally.

It loops or repeats itself

Symptom: Hermes runs the same step again and again, or a job never ends.

Likely cause: the model is stuck. Hermes's configuration page says that by default it puts no cap on steps in one reply, and that in a chat you are watching, its loop guard only warns the model instead of stopping it.

Fix: stop it with the first fix on this page, then type /new and give it a smaller job with one file and one folder. If loops keep happening, you can set a cap by adding max_turns: 30 under an agent: line in config.yaml. The number 30 is this guide's example, not a documented default. A spend limit at your provider is the backstop for paid keys.

What you should see the run ends, and a smaller job finishes.

It said it remembered, but the next chat forgot

Symptom: Hermes said "I'll remember that," and a new chat has no idea.

Likely cause: the memory docs list five causes and say the first explains most cases: the model never actually saved anything. Another is that you are still in the same chat, since new memories load only when a chat starts.

Fix: open USER.md or MEMORY.md in the memories folder and look for the fact. If it is missing, ask again and name the memory tool. If it is there, type /new and try again.

What you should see the fact in the file, and the new chat using it.

The phone bot does not answer

Symptom: your Telegram bot stays silent.

Likely cause: the gateway is not running, the computer is asleep, or your account is not on the allow list.

Fix: in a terminal, type hermes gateway status, and if it is not running, type hermes gateway start. The desktop app has a Keep computer awake setting under Settings, then Advanced, but the docs say closing a laptop lid still puts it to sleep. If your own messages get a pairing code, approve your own code as page 4 describes.

What you should see the bot answers your next message.

Update it safely

Symptom: you want a newer Hermes, and you want your chats, keys, and memory to survive the change.

Likely cause: none needed. Updating is a choice, and the copy comes before the new version.

Fix:

  1. Quit the desktop app, then run hermes gateway stop in a terminal. Copy the whole Hermes folder, which is %LOCALAPPDATA%\hermes on Windows and ~/.hermes on a Mac. That folder holds config.yaml, .env, auth.json, SOUL.md, state.db, memories, sessions, skills, and logs. Also copy the work folder you gave Hermes, such as agent-tryout inside Documents. A copy of either folder can live in Windows File History or Previous Versions, or in Mac Time Machine. Running hermes backup saves a hermes-backup- zip in your home folder with your settings, keys, memory, skills, chats, and profiles; keep that zip private, because it holds .env and auth.json. hermes update also takes a quick snapshot first, but the update page says that snapshot can fail and the update still goes on, so keep your own copy.

What you should see a second copy of the Hermes folder and of your work folder, stored outside both folders.

  1. Read the release notes before you install anything. For a command install, run hermes update. For the Windows sideload app, use the desktop Update control, which hands the package to Windows App Installer. For the Microsoft Store app, update it in the Store. On a Mac, use the desktop Update control. The update page says user data stays outside the app package. If Hermes is the Docker image, do not run hermes update inside the container. That command refuses and tells you to pull a new image, then recreate the container with the same data mount. The Docker page's commands are docker pull nousresearch/hermes-agent:latest, then docker rm -f hermes, then a new docker run that keeps the same volume. Its example mount is -v ~/.hermes:/opt/data. Use the mount you already have, and do not delete that folder or a named volume at /opt/data. This guide could not confirm the Windows form of that mount line. A past update set a chosen personality back to none one time. The personality page says a SOUL.md you already saved is never overwritten.

What you should see the update ends with no error, and Hermes opens again. If you had picked a personality, /personality may show none.

  1. Run hermes --version. Then ask Hermes to list the files in agent-tryout and to change nothing.

What you should see a version number, then a short file list, and no command that writes or deletes.

Uninstall or reset it cleanly

Symptom: you want Hermes gone, or you want a fresh start.

Likely cause: none, because this is a choice.

Fix: stop Hermes first. Quit the desktop app, then run hermes gateway stop. The Windows guide says that command waits up to 30 seconds, then forces the gateway to close. If you set the gateway to start at login, run hermes gateway uninstall to remove that login service without deleting your Hermes data folder.

What you should see hermes gateway status no longer shows a running gateway.

Remove the program, or the Docker container and image, and leave the data folder in place for this step.

What you should see Hermes is gone from the Start menu, the Applications folder, or Docker, and the Hermes data folder is still on disk.

Deleting the data folder erases settings, keys, memory, and chats for good. Make a zip with hermes backup first, and skip the rest of this step if you might install Hermes again. Before you remove a command install, you can choose 2 (Full uninstall) in hermes uninstall, or run hermes uninstall --full, which also asks whether to remove any named profiles. Before you remove a desktop or Docker install, hermes uninstall --data removes only the active home's user data, and after the app is removed you can instead delete %LOCALAPPDATA%\hermes on Windows or ~/.hermes on a Mac. The Windows guide warns against deleting that whole folder just to repair the app, because other installs can share it. On Docker, deleting the host folder or the named volume erases memory, and afterward you should revoke your model keys and bot tokens on each provider's website and in @BotFather.

What you should see no Hermes in your Start menu or Applications folder, and your data folder kept or removed, whichever you chose.

Sources

Research in this repo:

Official Hermes pages (checked 14 November 2026):

GitHub issues (checked 14 November 2026):

Next

Continue to Advanced.

Checked 14 November 2026 · prices, limits, and versions change