Troubleshooting

Troubleshooting Common Issues

Installation Problems

\”command not found: hermes\”

Add to PATH or restart shell:

export PATH=\"\$HOME/.local/bin:\$PATH\"
source ~/.bashrc

Python version errors

Requires Python 3.10+. Check with:

python3 --version

Permission denied on install

pip install --user hermes-agent
# or
pipx install hermes-agent

Configuration Issues

Model not found / API errors

• Verify API key in hermes auth status
• Check model name spelling in ~/.hermes/config.yaml
• Test with: hermes chat -Q -m deepseek/deepseek-v4-flash-0731 -q test

Gateway won’t start

hermes gateway status
tail -50 ~/.hermes/logs/gateway.log
# Common fix: install missing platform SDK
sudo ~/.local/lib/hermes-agent/venv/bin/python -m pip install python-telegram-bot[webhooks]==22.8

Telegram/Discord Not Working

• Check hermes gateway status — should show \”connected\”
• Verify bot token in hermes auth status
• Re-run hermes setup to reconfigure platforms

Skills Not Loading

hermes skills list
hermes skills install 
hermes doctor

Performance Issues

• Reduce context_length in config
• Disable unused toolsets per platform
• Use faster model (e.g., deepseek-v4-flash)

Reset Everything

hermes config reset
rm -rf ~/.hermes/skills
hermes setup

---

Still stuck? Check GitHub Issues or Discord.