Hermes Agent is one of the best open-source AI agent frameworks available. It also has bugs that will eat your weekend. Here are the 10 most reported issues from GitHub, Discord, and community forums, with real fixes for each one.
I maintain a running list of Hermes Agent bugs. Not because I enjoy cataloging other people's problems, but because our support team fields questions every week from developers migrating off self-hosted setups. "Did you hit the tool-call loop?" "Was it the dashboard Docker bug?" "Which version introduced the fd leak?"
After months of tracking GitHub issues, Discord threads, and community troubleshooting posts, these are the 10 Hermes agent bugs that show up the most. Each one includes the symptom, the root cause, the working fix, and a note on how managed platforms handle the same problem.
Hermes Agent has shipped aggressively in 2026. v0.13.0 "Tenacity" landed May 7 with 864 commits and 282 closed issues. v0.14.0 "Foundation" landed May 16 with 808 commits and 545 closed issues. That's 1,672 commits and 827 closed issues in 9 days. The pace is remarkable. But speed creates bugs. Here are the ones that affect real users.
Bug 1: Infinite tool-call loops (the agent that never finishes)
Symptom: You ask your agent to do a multi-step task ("fetch this webpage, extract content, save to file"). The agent starts, makes a tool call, gets a response... then loops. It keeps calling the same tool. Or it silently drops the remaining steps and returns an incomplete answer.
Root cause: The agent loop in run_agent.py sometimes receives an empty response after a tool call. Instead of retrying or escalating, it uses the earlier content as the final answer. GitHub issue #9400 documents this clearly: "The status line shows: ↻ Empty response after tool calls, using earlier content as final answer."
This is especially common with non-Claude models (GLM-5, some Ollama local models). But the root cause is in the agent loop design, not the model.
Fix: Set a maximum retry count for empty tool-call responses. In your configuration:
# ~/.hermes/config.yaml
agent:
max_empty_retries: 3
tool_call_timeout: 30
If you're running local models via Ollama, the hang is often caused by the stream+tools interaction (Ollama issue #2805). Switch to non-streaming mode:
hermes config set model.streaming false
How managed platforms handle this: BetterClaw's agent loop includes automatic retry logic with exponential backoff, a maximum iteration cap, and real-time anomaly detection that auto-pauses agents stuck in loops. You never see infinite tool calls because the system catches them before they burn through your token budget.
Bug 2: Token bloat on Telegram gateway (2-3x cost for same conversation)
Symptom: Your agent costs significantly more when accessed through Telegram compared to CLI. Same questions, same model, 2 to 3 times the input tokens.
Root cause: The gateway historically spawned in the hermes-agent directory, which loaded development files like AGENTS.md and other metadata as "garbage data" into the context. A community member documented this: "With some tools/skills enabled, Hermes uses around 6-8k input tokens in CLI, and around 15-20k input tokens when using Telegram."
Fix: The core fix was merged (Hermes should now start in the user's home directory). Update to the latest version:
hermes update
If token costs are still elevated, check what's being loaded into context:
hermes config env-path
ls -la $(hermes config path)
Remove any .md files in the Hermes directory that shouldn't be there.
The deeper issue: Token bloat is structural in most self-hosted agent frameworks because there's no incentive to optimize context size. Every extra token is the user's cost, not the platform's. Managed platforms that charge per-agent (not per-token) have a direct incentive to keep context lean.
For how smart context management prevents this exact problem, our guide on hidden costs of OpenClaw agents covers the token bloat problem in detail.
Bug 3: Dashboard fails to start in Docker (read-only overlayfs)
Symptom: You run hermes dashboard inside the official Docker container. It fails immediately with: "Web UI npm install failed. Run manually: cd web && npm install && npm run build."
Root cause: In the official Docker image, /opt/hermes/web is part of the committed image layers (overlayfs lowerdir). When the dashboard tries to run npm install, it attempts to create node_modules in a read-only filesystem layer. Even root inside the container can't write there. GitHub issue #12243 tracks this.
Fix: Mount a writable volume over the web directory:
docker run -d --name hermes \
-v /data/hermes:/opt/data \
-v /data/hermes-web:/opt/hermes/web \
-p 9119:9119 \
nousresearch/hermes-agent:latest
Or run the npm build outside the container and copy the artifacts in.
Alternatively, use the HERMES_DASHBOARD=1 environment variable (added in v0.13.0 by contributor @benbarclay) to launch the dashboard as a side-process, which handles the filesystem issue differently.
Bug 4: Ollama local models hang indefinitely with tool definitions
Symptom: You configure Hermes with a local Ollama model. The agent never responds. No error. No timeout. Just silence.
Root cause: Ollama's /v1/chat/completions endpoint hangs when stream=true and tool definitions are included. This is tracked as Ollama issue #2805. Hermes's pre-flight provider detection also interferes with proxy setups like LiteLLM. GitHub issue #25629 has a detailed reproduction.
Fix:
Option 1: Use the native Ollama API mode instead of OpenAI-compatible:
hermes config set model.api_mode chat
Option 2: Add a provider detection bypass:
hermes config set model.skip_provider_detection true
Option 3: Use a LiteLLM proxy between Hermes and Ollama. LiteLLM handles the stream+tools interaction correctly. But Hermes's pre-flight detection needs to be disabled for this to work.
Bug 5: CLI crash on startup ("Invalid key 'c-S-c'")
Symptom: You launch Hermes. It crashes immediately before you can type anything.
Root cause: A P0 bug in the prompt_toolkit integration. The key binding c-S-c (Ctrl+Shift+C) uses a Shift modifier that prompt_toolkit doesn't support. Fixed in v0.13.0 (issues #19895, #19919).
Fix: Update to v0.13.0 or later:
hermes update
If you can't update, the workaround is to downgrade prompt_toolkit to a version before the keybinding was added. But updating is the right answer here.
Bug 6: CLOSE_WAIT file descriptor leak (WhatsApp and Feishu)
Symptom: After running for several days, Hermes becomes unresponsive. Memory usage climbs steadily. Eventually the process runs out of file descriptors and stops accepting connections.
Root cause: An httpx keepalive leak combined with WhatsApp's aiohttp adapter and Feishu's connection hygiene. Connections enter CLOSE_WAIT state and never close. This was audited and fixed in v0.13.0 (issues #18451, #18766).
Fix: Update to v0.13.0+. If you're running an older version, add a periodic gateway restart to your cron:
0 */6 * * * systemctl restart hermes-gateway
Not elegant, but it keeps the process alive between updates.
If every bug on this list sounds like infrastructure babysitting instead of agent building, that's because it is. We built BetterClaw specifically because debugging file descriptor leaks at 2 AM is not why anyone got interested in AI agents. Free plan available. $19/month for Pro. We handle the fd leaks. You handle the workflows.
Bug 7: DeepSeek V4 Pro gateway crash loop
Symptom: Your Telegram bot (and all messaging integrations) goes completely unresponsive after configuring DeepSeek V4 Pro via OpenRouter.
Root cause: OpenRouter's upstream provider applies aggressive rate limits. When hit, the gateway doesn't recover. It crash-loops. GitHub issue #16677, labeled P1 (major feature broken, no workaround).
Fix: Use a personal DeepSeek API key (not the shared OpenRouter pool), or switch to the DeepSeek direct API:
hermes config set model.provider deepseek
hermes config set model.default deepseek-v4-pro
Related: DeepSeek V4 Pro sessions show "unknown cost" in analytics due to a cost-tracking bug (#24218). Exclude from spend reports until patched.
For a complete breakdown of AI model pricing and which providers work best for agents, our cheapest AI providers guide covers cost-per-task comparisons.
Bug 8: Windows native beta encoding crash
Symptom: On Windows (no WSL), any file or directory operation with non-ASCII characters crashes with: 'charmap' codec can't encode characters in position 0-29.
Root cause: Windows uses cp1252 encoding. Hermes assumes UTF-8. GitHub issue #16201: "directory and file handling on windows has major problems."
Fix:
$env:PYTHONUTF8 = "1"
hermes
Or disable the Windows UTF-8 shim:
$env:HERMES_DISABLE_WINDOWS_UTF8 = "1"
For the full list of Windows-specific issues and workarounds, our Hermes Docker installation guide covers containerized alternatives that bypass Windows bugs entirely.
Bug 9: Cold-start performance (19 seconds of import overhead)
Symptom: Running hermes takes 15 to 25 seconds before the prompt appears. On lower-spec machines, even longer.
Root cause: Import overhead and network calls during startup. Hermes loads all providers, tools, and skills upfront. v0.14.0 specifically targeted this with a "cold-start performance wave" that cut ~19 seconds off launch time. Heavyweight backends now lazy-install on first use.
Fix: Update to v0.14.0 (from Git, not PyPI, which still serves v0.13.0 as of May 18):
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
If you can't update, disable unused providers and tools in config to reduce startup load:
# ~/.hermes/config.yaml
toolsets:
disabled:
- browser
- vision
- code_execution
Bug 10: Session memory leak (ghost sessions with incomplete metadata)
Symptom: Over time, your agent's session list fills with broken entries. Session analytics show sessions that never properly closed. Memory usage creeps upward.
Root cause: The TUI compression feature created "ghost sessions" with incomplete metadata (issue #20001). Combined with the CLOSE_WAIT fd leak (#18451), long-running Hermes instances accumulate dead sessions that consume memory.
Fix: Clean old sessions:
hermes sessions clean --before 2026-05-01
Update to v0.13.0+ where ghost session creation was fixed. For ongoing maintenance:
0 0 * * 0 hermes sessions clean --before $(date -d '-30 days' +%Y-%m-%d)
The pattern across all 10 bugs
Here's what nobody tells you.
Every bug on this list falls into one of three categories: infrastructure management (Docker, file systems, PATH, encoding), provider-specific edge cases (DeepSeek, Ollama, OpenRouter), or long-running process maintenance (fd leaks, ghost sessions, token bloat).
None of them are about building agents. None are about designing workflows, writing skill logic, or connecting to chat platforms.
That's the actual cost of self-hosting. The agent framework is free. The bugs are expensive.
Hermes is genuinely impressive. 808 commits in 9 days for v0.14.0. Microsoft Teams support. Windows native beta. xAI Grok integration. Native video generation. The feature velocity is extraordinary. But velocity creates bugs, and bugs require your time.
The honest question isn't "is Hermes good?" It is. The question is: do you want to build agents, or maintain agent infrastructure?
If your answer is "build agents," give BetterClaw a try. Free plan with 1 agent and every feature. $19/month per agent for Pro. 200+ verified skills. 28+ AI model providers. Deploy in 60 seconds. We handle the 10 bugs above (and hundreds more you'll never see). You handle the interesting part.
Frequently Asked Questions
What are the most common Hermes agent bugs in 2026?
The most common Hermes agent bugs are infinite tool-call loops (agent loops without completing tasks), token bloat on the Telegram gateway (2-3x cost increase), dashboard not loading in Docker (read-only overlayfs issue), Ollama local models hanging indefinitely, and the DeepSeek V4 Pro gateway crash loop. Most are fixed in v0.13.0 or v0.14.0, but some (like the DeepSeek P1 crash) remain open.
How do I fix Hermes agent not working after an update?
First, run hermes doctor to check your installation health. Then verify your config with hermes config path and hermes config env-path. Make sure your provider API key is actually set (the setup wizard sometimes skips the key prompt). If the gateway crashes, check Docker volume permissions and restart with hermes gateway restart. For version-specific issues, note that PyPI serves v0.13.0 even though v0.14.0 is the latest source release (May 18, 2026).
Why does my Hermes agent keep looping on tool calls?
Infinite tool-call loops happen when the model returns an empty response after a tool call, and the agent loop retries without a maximum cap. This is most common with non-Claude models and local Ollama setups. Set max_empty_retries: 3 in your config and consider disabling streaming (model.streaming: false) for Ollama backends. BetterClaw's agent loop handles this automatically with retry caps and anomaly detection.
How much does it cost to run Hermes Agent vs a managed platform?
Hermes Agent is free (MIT license), but self-hosting costs $5 to $50/month for a VPS, plus 15+ hours for initial setup and 2 to 5 hours/month for maintenance (updating, debugging, monitoring). BetterClaw's free plan includes 1 agent with managed hosting at $0/month. Pro is $19/agent/month with unlimited tasks. When you include hosting, maintenance time, and the token bloat that self-hosted setups often produce, BetterClaw Pro is frequently cheaper than self-hosting.
Is the Hermes Agent web UI dashboard reliable?
The built-in dashboard (hermes dashboard) works well on local installs but has known issues in Docker (read-only overlayfs prevents npm install, issue #12243) and requires optional extras (FastAPI, Uvicorn) that aren't installed by default. Third-party dashboards like hermes-web-ui offer more features but add complexity. A session memory leak (ghost sessions with incomplete metadata, issue #20001) was fixed in v0.13.0. For server deployments, the official docs recommend putting the dashboard behind auth and never exposing it publicly.
