Troubleshooting Common Issues

Source: r/hermesagent Help/Issue threads (May 2026)

Quick Diagnostic Flowchart

1. Hermes won't start -> Check "Invalid key" error, gateway config
2. Agent forgets things -> Memory system not configured or context too long
3. Tool calls failing -> Model capability issue, try different model
4. High token costs -> Wrong model tiering, no caching, frequent model switching
5. Gateway crashes after update -> Check compatibility, restore from backup
6. Agent hallucinates actions -> Verify tool outputs, use verification workflow

Common Errors and Fixes

"Error: Invalid key: c-S-c"

Reported by: u/thechadwicked (5 upvotes)

• Symptom: Error on every Hermes startup, can't do anything after
• Likely cause: Keyboard shortcut conflict or corrupted config
• Fix: Check config.yaml for malformed entries, especially around key bindings

Agent Edits Its Own Code

Reported by: u/insidesliderspin (18 comments)

• Symptom: Hermes edited gateway platform Python files to "fix" bugs it thought it found
• Is this normal? Yes - Hermes is designed to edit its own workspace files
• How to control: Set boundaries in SOUL.md or AGENTS.md about which directories/files are off-limits
• Recommendation: Use git for version control so you can revert unwanted changes

Google Account Disabled

Reported by: u/xDeepS (14 comments)

• Symptom: Hermes's dedicated Google account disabled after 7 days
• Cause: Automated behavior triggered Google's spam/abuse detection
• Fix: Use a burner account, warm it up gradually before heavy automation
• Prevention: Space out API calls, avoid rapid account creation patterns

Agent Says It Did Something But Didn't

Reported by: u/HsbndThrwAwyMnoPs (14 comments)

• Symptom: Hermes claims to have added info to Obsidian, shows proof with images, but files unchanged
• Root cause: Hallucination or failed write not properly error-checked
• Fix: Always verify file writes independently after agent reports completion
• Prevention: Use tool verification workflow - ask agent to read back what it wrote

Fresh Install Not Remembering Messages

Reported by: u/PM_ME_UR_CODEZ (14 comments)

• Symptom: Hermes doesn't remember previous messages in conversation
• Cause: Memory system not configured or session management issue
• Fix: Configure a memory provider (Hindsight recommended), check session persistence settings

Agent Forgets What It Has Access To

Reported by: u/SandStorm1863 (26 comments)

• Symptom: After a month, Hermes forgets about sub-agents, tools, capabilities
• Fixes discussed:
  • List available tools explicitly in SOUL.md or context files
  • Create "capabilities" reference note in Obsidian
  • Use memory system to store tool access patterns
  • Periodically remind agent of its setup

Hermes Eating Through Token Limits

Reported by: u/PrincessAlbertPW (15 comments)

• Symptom: MiniMax token plan request limit exhausted quickly
• Solutions:
  • Direct simpler tasks to cheaper model with higher limits
  • Use auxiliary model for subtasks
  • Reduce context window size if not needed
  • Set up model routing (cheap model for simple tasks, expensive for complex)

Display Sleep Kills Session

Reported by: u/Sadboyfornow (13 comments)

• Symptom: When display monitor turns off during sleep, Hermes session dies
• Cause: System sleep suspends gateway process
• Fixes:
  • Disable display sleep while keeping system awake
  • Run Hermes on always-on hardware (NAS, VPS, Mac Mini)
  • Use cron jobs for scheduled tasks (persist independently of sessions)

Model-Specific Issues

Censored Models Refusing Tasks

Reported by: u/Jonathan_Rivera (11 comments)

• Symptom: Model refuses browser automation on external portals (e.g., school parent portal)
• Cause: Safety filters in censored model variants
• Fix: Use abliterated/uncensored variant of the same model
• Trade-off: Uncensored models may have slightly reduced accuracy

GLM 5.1 Tool Call Errors

Reported by: u/bef349

• Symptom: "Model generated invalid tool call" messages, connection drops
• Status: Model overloaded/unstable at time of writing
• Fix: Switch to different model temporarily

MiniMax Inconsistency

Reported by: u/idefix1515 (17 comments)

• Symptom: "All over the place" - inconsistent quality between sessions
• Cause: Model capability limits, especially for complex multi-step tasks
• Fix: Use MiniMax for simple tasks only, upgrade model for complex work

Local Model Performance Issues

Reported by: u/Clean_Initial_9618 (RTX 3090, 24GB VRAM)

• Symptom: Slow responses with Qwen 3.6 locally, breaking code
• Hardware: RTX 3090 (24GB), 64GB RAM, Ryzen 5700X, Windows 11
• Solutions discussed:
  • Use vLLM instead of Ollama for better performance
  • Try lower quantization (Q4 instead of Q8)
  • Consider cloud model for complex tasks

Cost Optimization

Spending Too Much on OpenRouter

Reported by: u/Maleficent-Anything2

• Symptom: Spent $10 in one day with DeepSeek V4 through OpenRouter (expected 25c)
• Cause: OpenRouter may not cache as effectively as direct API
• Fix: Switch to DeepSeek direct API - same model, half the price with better caching

General Cost Reduction Strategies

1. Use direct APIs when settled on a model (avoid OpenRouter markup)
2. Tier your models - cheap auxiliary model for simple tasks
3. Enable caching where available (DeepSeek excels here)
4. Reduce model switching - each switch re-reads full chat history
5. Keep conversations focused - shorter sessions = less context to maintain
6. Use free-tier pooling with llm-keypool for zero-cost operation

Stability and Updates

Has Hermes Ever "Died"?

Reported by: u/Pepe_The_Citizen (12 comments)

• Question: Stability issues with general operations and updates?
• Community consensus: Generally stable, but:
  • Major updates occasionally break custom configs
  • Keep backups of ~/.hermes directory before updating
  • Gateway restarts are normal and don't lose state

Insane Token Count After OpenClaw Migration

Reported by: u/bumkinas (3 comments)

• Symptom: Very high token counts after migrating from OpenClaw
• Cause: Importing large conversation histories, redundant context
• Fix: Start fresh sessions after migration, prune old context

Initial Prompt Too Large

Reported by: u/ThisMacaroon9270 (2 comments)

• Symptom: Hermes starts with ~10k context vs Pi agent's 1k
• Question: Can I start with minimal skills and load more as needed?
• Answer: Use profiles with lean SOUL.md files, load skills on-demand

Security Concerns

Running Hermes on Main PC

Reported by: u/stevehl42 (23 comments)

• Question: Security setup for running Hermes on primary computer?
• Community approaches:
  • Dedicated user account with limited permissions
  • Docker containerization for isolation
  • Separate GitHub account for agent's code commits
  • Guardrails in SOUL.md about what files to access

File Sharing on VPS

Reported by: u/Smooth-Plan4769 (9 comments)

• Question: Best way to share folders/files with Hermes on VPS without PC data exposure?
• Solutions discussed:
  • Dedicated shared directory with limited scope
  • Syncthing for selective file sync
  • SFTP with restricted user access

Prompt Injection Risks

Reported by: u/mseewald (private setup thread)

• Warning: Calendar invite prompt injection is real - malicious invites can extract private meeting data
• Local models are LESS safe against prompt injection than frontier models with built-in safeguards
• Recommendation: Use shared calendar/email rather than full access, maintain snapshots and backups

Docker-Specific Issues

Can't Access Web Interface on Synology NAS

Reported by: u/Ok_Version_3193 (9 comments)

• Symptom: Hermes Agent + Dashboard installed via Docker but web interface inaccessible
• Common fixes:
  • Check port mappings in docker-compose.yml
  • Verify firewall settings on NAS
  • Ensure container is running: docker ps
  • Check container logs: docker logs hermes

Transferring from VPS to Local Docker

Reported by: u/Smooth-Plan4769 (4 comments)

• Question: Can I transfer Hermes installation from VPS to local Docker?
• Answer: Yes - copy ~/.hermes directory and use as volume mount in new container

When to Ask the Community

If your issue isn't covered here, post on r/hermesagent with:

1. Clear description of the problem
2. Your setup (model, hosting method, OS)
3. Error messages or logs
4. What you've already tried

Use the "Help / Issue / Questions" flair for maximum visibility.