# 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.