Troubleshooting Hermes Agent: 15 Common Problems & Solutions

Hermes isn’t responding. Your bot vanished from Discord. Memory isn’t persisting.

Here’s the fix for every common problem.

Installation & Setup Issues

”Installation script fails”

Symptom: curl command fails or script hangs.

Diagnosis:

# Check curl
which curl

# Check internet
ping github.com

# Check permissions
ls -la ~

Fix:

• curl not found: Install curl (brew install curl on Mac, sudo apt install curl on Ubuntu)
• Network issue: Wait, retry. GitHub might be slow
• Permission issue: Run as same user (not sudo)

Prevention: Use stable internet, don’t use sudo.

”hermes: command not found”

Symptom: After install, hermes --version fails.

Diagnosis:

# Check if installed
ls ~/.hermes/bin/hermes

# Check PATH
echo $PATH

Fix:

# Add to PATH
export PATH="$HOME/.hermes/bin:$PATH"

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Prevention: Restart terminal after install.

Platform Connection Issues

”Discord bot not responding in channel”

Symptom: Bot in server but doesn’t reply to @mentions.

Diagnosis:

hermes status
# Check: Discord connected?

# Check bot permissions
# Go to Discord → Server Settings → Roles → hermes_bot
# Does it have "Send Messages"?

Fix:

1. Check bot has channel permissions (Discord server settings)
2. Verify token is correct: hermes config show
3. Restart bot: hermes disconnect discord && hermes connect discord

Prevention: Set bot permissions correctly during setup.

”Slack bot only works in DMs”

Symptom: Bot responds in direct messages, not channels.

Diagnosis:

hermes config show | grep slack
# Check: which channels listed?

Fix:

1. Add bot to specific channels (Slack UI)
2. Update config: hermes setup → choose Slack channels
3. Restart Hermes

Prevention: Configure channels explicitly during setup.

”Telegram bot receives messages but doesn’t reply”

Symptom: Bot shows “typing…” but never responds.

Diagnosis:

hermes status
# Check Telegram: "connected"?

# Test LLM connection
hermes test-llm

Fix:

• Not connected: Restart Hermes
• LLM not responding: Check hermes test-llm output
• Token expired: Regenerate in BotFather, update Hermes

Prevention: Run hermes status regularly.

”Token invalid or expired”

Symptom: Platform connection fails immediately.

Diagnosis:

# Check config for typos
cat ~/.hermes/config.yml | grep -i token

Fix:

1. Discord: Go to Discord Developer Portal, regenerate token
2. Slack: Go to Slack App, get new token
3. Telegram: Chat @BotFather, /token, get new token
4. Update Hermes: hermes setup → re-enter token

Prevention: Copy tokens carefully. Test immediately after.

Learning & Memory Issues

”Skills aren’t being generated”

Symptom: Hermes solves tasks but no skill documents appear.

Diagnosis:

# Check memory directory exists
ls -la ~/.hermes/memory/skills/

# Check config
grep "skill" ~/.hermes/config.yml

Fix:

# ~/.hermes/config.yml
memory:
  skill_generation: true  # Might be disabled
  skill_auto_save: true

Then restart Hermes.

Prevention: Check config after setup.

”Agent forgets previous conversations”

Symptom: Ask same question again, Hermes acts like first time.

Diagnosis:

# Check conversation history
ls -la ~/.hermes/memory/conversations/

# Check file size (should grow over time)
du -sh ~/.hermes/memory/

Fix:

1. Memory disabled: Check memory: true in config
2. Memory corrupted: rm ~/.hermes/memory/conversations/* (careful!)
3. Wrong storage backend: Reinstall: curl -fsSL ... | bash

Prevention: Verify memory size grows: du -sh ~/.hermes/memory/ weekly.

”Memory storage growing too large”

Symptom: ~/.hermes/ takes 5GB+ of disk.

Diagnosis:

du -sh ~/.hermes/memory/*
# Which folder is largest?

Fix:

# Prune old conversations
hermes memory prune --older-than 180days

# Prune unused skills
hermes skills prune --unused 90days

# Check size again
du -sh ~/.hermes/memory/

Prevention: Run prune monthly: hermes memory prune --auto.

Performance Issues

”Responses are very slow”

Symptom: Hermes takes 30+ seconds per response.

Diagnosis:

# Check LLM latency
hermes test-llm
# Note response time

# Check system resources
top  # (or Activity Monitor on Mac, Task Manager on Windows)
# CPU? Memory maxed?

Fix:

1. LLM provider slow: Use faster model or provider
2. System overloaded: Close other apps, add RAM
3. Network issues: Check internet speed
4. Memory too large: Prune old files (see above)

Prevention: Monitor hermes status for latency.

”Agent crashes under load”

Symptom: Bot works for one conversation, then crashes.

Diagnosis:

# Check logs
tail -50 ~/.hermes/logs/hermes.log | grep ERROR

# Check memory
hermes status | grep memory

Fix:

# ~/.hermes/config.yml
performance:
  max_concurrent_tasks: 1  # Reduce from default
  max_memory_mb: 4096      # Cap memory usage

Restart: hermes.

Prevention: Limit concurrency on low-RAM machines.

”Memory usage climbing over time (memory leak)”

Symptom: top shows Hermes using 1GB, then 2GB, then 4GB.

Diagnosis:

# Monitor memory
watch -n 5 'ps aux | grep hermes'

# Check for large cache
du -sh ~/.hermes/cache/

Fix:

memory:
  cache_ttl: 3600  # Clear cache every hour
  cache_limit_mb: 512  # Cap cache size

Restart Hermes.

Prevention: Monitor memory weekly.

LLM Backend Issues

”Ollama not found at http://localhost:11434”

Symptom: Hermes says “Can’t connect to Ollama.”

Diagnosis:

# Check if Ollama running
ps aux | grep ollama

# Check Ollama status
curl http://localhost:11434/api/tags

Fix:

# Start Ollama
ollama serve

# In another terminal, verify
curl http://localhost:11434/api/tags

# Update Hermes config if needed
hermes setup  # Re-select Ollama endpoint

Prevention: Start Ollama before starting Hermes.

”API rate limited (cloud provider)”

Symptom: “Rate limit exceeded” error when using OpenAI/Anthropic.

Diagnosis:

grep "rate_limit" ~/.hermes/logs/hermes.log

Fix:

# ~/.hermes/config.yml
inference:
  rate_limit:
    requests_per_minute: 10
    batch_requests: true  # Batch multiple together

Prevention: Monitor API usage, add delays between requests.

Diagnostic Commands Reference

# Check overall status
hermes status

# Test LLM connection
hermes test-llm

# View config
hermes config show

# View logs (last 50 lines)
tail -50 ~/.hermes/logs/hermes.log

# Follow logs in real-time
tail -f ~/.hermes/logs/hermes.log

# Check memory size
du -sh ~/.hermes/memory/

# List connected platforms
hermes platforms list

# Verify installation
hermes --version

When to Ask for Help

Before posting on GitHub:

1. Run hermes status and save output
2. Check logs: tail -100 ~/.hermes/logs/hermes.log
3. Try the fix above for your issue
4. If still broken, go to github.com/NousResearch/hermes-agent/issues

Include:

• Error message (full, not summary)
• Output of hermes --version
• Relevant config (redact tokens)
• Steps to reproduce

Common Quick Fixes (Try These First)

1. Restart Hermes: pkill hermes && sleep 2 && hermes
2. Restart platform connection: hermes disconnect [platform] && hermes connect [platform]
3. Clear cache: rm -rf ~/.hermes/cache/*
4. Reinstall: Delete ~/.hermes and run install script again

Most issues resolve with restart or config adjustment.

FAQ

Q: Is my data lost if Hermes crashes? No. Memory is on disk. Restart and it’s all there.

Q: How do I debug Hermes? Run with hermes --debug for verbose logging.

Q: Can I reset Hermes to factory settings? Yes: rm ~/.hermes && curl -fsSL ... | bash

Q: Where are logs stored? ~/.hermes/logs/hermes.log

What to Read Next

• Advanced Configuration — Prevent these issues
• Security — Secure your setup
• Install Guide — Fresh start

Still stuck? Check GitHub issues or ask in the community Discord. Hermes community is helpful.

Related Articles

Deepen your understanding with these curated continuations.

View All Articles

Hermes Agent5 min read

Connect Hermes Agent to Discord: Step-by-Step Gateway Setup

Configure the Discord gateway for Hermes Agent v0.17.0 using the new Web Admin Panel. A complete setup guide for developer agents.

Darsh JariwalaJun 22, 2026

Hermes Agent5 min read

Advanced Hermes Agent: Optimization, Scaling & Learning Loop Tuning

Make your Hermes Agent production-grade. Optimize the learning loop, scale to thousands of users, and tune every parameter.

JenaApr 30, 2026

Hermes Agent5 min read

How Hermes Agent Learns: Architecture & The Self-Improvement Loop

Most AI agents forget everything. Here's exactly how Hermes remembers, learns, and gets smarter with every task it solves.

VishnuApr 30, 2026