Common Errors

When using Hermes Agent, you may encounter various errors. This page compiles the most common errors and their solutions to help you quickly identify and fix issues.

command not found: hermes

Symptom: Terminal shows “command not found” when typing hermes.

Cause: Shell environment variables not refreshed after installation, or PATH configuration incorrect.

Solutions:

# Method 1: Reload shell configuration
source ~/.bashrc      # Bash users
source ~/.zshrc       # Zsh users

# Method 2: If Method 1 fails, reopen terminal window

# Method 3: Check if hermes is in PATH
which hermes
# If not found, manually add:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Tip

If you installed via pip, hermes may be in the ~/.local/bin/ directory. Make sure this path is added to PATH.

API Key Not Set or Invalid

Symptom: LLM connection fails when running hermes chat, or 401 Unauthorized error.

Cause: API Key not configured, expired, or entered incorrectly.

Solutions:

# Method 1: Use interactive configuration wizard
hermes model

# Method 2: Manually edit configuration file
# Open ~/.hermes/config.yaml and verify these fields:

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  api_key: sk-or-v1-xxxxx    # Confirm Key is correct and valid

# Method 3: Use environment variables (good for Docker deployments)
export LLM_API_KEY=sk-or-v1-xxxxx

Caution

Do not hardcode API Keys in public configuration files. Use environment variables or ~/.hermes/.env file instead.

Configuration File Missing or Corrupted

Symptom: Configuration file read error on startup, or abnormal behavior.

Cause: ~/.hermes/config.yaml file deleted, format error, or encoding corruption.

Solutions:

# Method 1: Reset config to defaults (preserves memory and skills)
hermes config reset

# Method 2: Manually rebuild minimal config
mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  api_key: ${LLM_API_KEY}
EOF

# Method 3: Use doctor to diagnose
hermes doctor

Port Conflict

Symptom: Port already in use error when starting gateway service.

Cause: Another Hermes Agent instance or service is using the same port.

Solutions:

# Find process using the port
lsof -i :8080          # macOS / Linux
netstat -ano | grep 8080   # Windows

# Kill the occupying process
kill -9 <PID>          # macOS / Linux

# Or change the port Hermes uses
# In ~/.hermes/config.yaml:

gateway:
  port: 8081    # Use an available port

Note

If you run both WebUI and message gateway, they use different ports by default. Make sure they don’t conflict.

ModuleNotFoundError

Symptom: Python module not found error on startup.

Cause: Python dependency package missing or virtual environment corrupted.

Solutions:

# Method 1: Reinstall Hermes Agent
pip install --force-reinstall hermes-agent

# Method 2: If installed from source, reinstall dependencies
cd ~/.hermes-agent
pip install -r requirements.txt

# Method 3: Ensure using correct virtual environment
source ~/.hermes-agent/.venv/bin/activate

Permission Denied

Symptom: Insufficient permissions when reading/writing ~/.hermes/ directory.

Cause: Incorrect directory ownership, possibly from running Hermes with sudo before.

Solutions:

# Fix directory ownership
sudo chown -R $(whoami):$(whoami) ~/.hermes

# Verify permissions
ls -la ~/.hermes/

Caution

Never run Hermes Agent with sudo. This will change config files and directory ownership to root, preventing normal users from reading/writing later.

Agent Unresponsive or Hanging

Symptom: Agent takes a long time to respond after sending a message.

Cause: Network connection issues, LLM API timeout, or incorrect proxy configuration.

Solutions:

# 1. Check network connectivity
curl -I https://openrouter.ai/api/v1/models

# 2. If using proxy, ensure it's configured correctly
export HTTPS_PROXY=http://127.0.0.1:7890

# 3. Try switching to another LLM provider
hermes model    # Choose a local provider like DeepSeek or Kimi

# 4. Press Ctrl+C to interrupt current request, then resend

Rate Limit Exceeded

Symptom: Frequent 429 rate limit errors.

Cause: API request frequency exceeded provider’s limit.

Solutions:

# 1. Wait 60 seconds and retry

# 2. Set auto-retry in configuration

~/.hermes/config.yaml

llm:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  retry:
    max_retries: 3
    retry_delay: 5

# 3. Upgrade API plan or switch to provider with higher limits
# 4. Use OpenRouter as middleware for automatic routing and retry

Garbled Chinese Output

Symptom: Chinese characters display as garbled text in terminal.

Cause: Terminal encoding settings incorrect.

Solutions:

# Set terminal encoding to UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Windows PowerShell users:
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

Tip

We recommend using Windows Terminal, iTerm2, or other modern terminal emulators that natively support UTF-8 encoding.

Memory Not Persisting

Symptom: Agent forgets previous conversations and preferences after restart.

Cause: Multiple instances writing to ~/.hermes/ directory simultaneously, or data directory not properly mounted (Docker scenario).

Solutions:

# 1. Ensure only one Hermes Agent instance is using ~/.hermes/
hermes session list
hermes session kill --all    # Clean up residual sessions

# 2. Docker users: Confirm data volume is mounted correctly
docker run -v /path/to/hermes-data:/root/.hermes ...

# 3. Check if memory files exist
ls ~/.hermes/memory/

General Troubleshooting Flow

When encountering issues, try in this order:

1. Run hermes doctor — Automatically diagnose common issues
2. Run hermes config reset — Reset configuration (preserves memory and skills)
3. Run hermes cache clear — Clear temporary caches
4. Check Install Issues and Model Issues
5. For complete reset:

cp -r ~/.hermes ~/.hermes.backup    # Backup first
rm -rf ~/.hermes                      # Clear all data
hermes model                          # Reconfigure

Related Pages

• Install Issues — Common installation problems
• Model Issues — LLM provider related issues
• Gateway Issues — Messaging platform connection issues
• hermes doctor — Automatic diagnostic tool