Troubleshooting — Common Issues and Fixes for Hermes Agent

By Hermes Agent··6 min read·troubleshootingdebugginghermes-agentquickstart

Solve common Hermes Agent issues including health check failures, API errors, configuration problems, and system recovery to get your agent back online.

![HERO_IMAGE_PROMPT: A high-tech digital diagnostic dashboard showing a stylized robotic agent with a magnifying glass, circuit board patterns in the background, neon blue and amber accents, cinematic lighting, 4k resolution]

Home > Quick Start Guides > Troubleshooting

The Hermes Agent is designed for resilience, but complex integrations with LLM providers, MCP servers, and local environments can occasionally lead to instability. This guide provides a systematic approach to diagnosing and resolving the most common issues.

🩺 System Health Checks

Before diving into manual debugging, use the built-in diagnostic suite to identify the root cause of the failure.

The hermes doctor Command

The doctor command scans your environment for missing dependencies, invalid API keys, network latency, and configuration syntax errors.

hermes doctor

What this checks:

  • Connectivity: Pings the configured LLM gateway.
  • Permissions: Verifies read/write access to the .hermes/ config directory.
  • Dependencies: Checks if required binaries (e.g., Python, Node, MCP hosts) are in the PATH.
  • Config Integrity: Validates config.yaml against the latest schema.

Automated Repair

If the doctor identifies common misconfigurations (such as incorrect directory permissions or outdated cache files), you can attempt an automated fix:

hermes doctor --fix

Note: --fix will not modify your API keys or model preferences, but it may reset temporary cache files and update local symlinks.

🛠 Common Issues and Fixes

1. API Key & Authentication Errors (401/403)

Symptoms: Agent returns Authentication Error, Invalid API Key, or HTTP 401 Unauthorized.

  • Check for Whitespace: Ensure no trailing spaces or quotes were accidentally pasted into your .env or config.yaml.
  • Verify Provider Status: Check the status page of your provider (OpenAI, Anthropic, Google, etc.).
  • Key Rotation: If you recently rotated keys, restart the Hermes daemon to force a reload of environment variables.
  • Quota Limits: A 429 Too Many Requests error is often mistaken for an auth error. Check your billing dashboard.

2. Provider Connectivity & Gateway Timeouts

Symptoms: Gateway Timeout (504), Connection Refused, or “Agent is unresponsive.”

  • Proxy Settings: If you are behind a corporate firewall, ensure HTTP_PROXY and HTTPS_PROXY environment variables are set.
  • DNS Issues: Try pinging the provider endpoint manually. If it fails, flush your DNS cache.
  • Gateway Latency: If using a local gateway (e.g., LiteLLM or Ollama), ensure the service is running: 
    # Example for Ollama
systemctl status ollama

3. Model Switching Problems

Symptoms: Agent continues using a previous model despite updating the config, or returns Model Not Found.

  • Cache Flush: Hermes caches model capabilities to speed up routing. Clear the cache: 
    hermes cache clear --models
  • Case Sensitivity: Ensure the model string exactly matches the provider’s requirements (e.g., gpt-4-turbo vs GPT-4-Turbo).
  • Availability: Verify that your account has access to the specific model version you are requesting.

4. Session & Context Errors

Symptoms: Agent “forgets” previous messages, returns Context Window Exceeded, or crashes during long conversations.

  • Context Pruning: Check your max_tokens and context_window settings in config.yaml. If the window is too small, the agent may crash when attempting to summarize.
  • Session Corruption: If a specific thread is behaving erratically, delete the session file: 
    rm ~/.hermes/sessions/[session_id].json
  • Token Overflow: Reduce the number of active plugins attached to the session to free up system prompt space.

5. Installation & Binary Issues

Symptoms: command not found: hermes, Shared library missing, or Segmentation fault.

  • PATH Verification: Ensure the Hermes binary directory is in your system PATH.
  • Architecture Mismatch: Ensure you downloaded the correct binary for your OS (e.g., arm64 for Apple Silicon vs x86_64 for Intel).
  • Dependency Conflict: If using a Python-based plugin environment, recreate your venv: 
    rm -rf .venv && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

6. Plugin Failures

Symptoms: Plugins fail to execute, return null responses, or cause the agent to loop.

  • Permission Denied: Ensure the agent has execution permissions for the plugin script: 
    chmod +x ~/.hermes/plugins/my-plugin.sh
  • Schema Mismatch: Update your plugins to the latest version to ensure compatibility with the current Hermes Agent API.
  • Timeout Settings: Increase the plugin_timeout value in your config if the plugin performs heavy computations.

7. MCP (Model Context Protocol) Server Errors

Symptoms: MCP Server not reachable, JSON-RPC Error, or tools not appearing in the agent’s capability list.

  • Stdio Check: Most MCP servers communicate via stdio. Ensure no other process is locking the server’s output.
  • Log Inspection: Check the MCP logs: 
    tail -f ~/.hermes/logs/mcp.log
  • Configuration Syntax: Ensure the MCP server is correctly defined in the mcpServers block of your config: 
    mcpServers:
  sqlite:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-sqlite", "--db", "/path/to/db"]

8. Memory Corruption & State Issues

Symptoms: Random crashes, “Unexpected token” in config, or persistent hallucinations despite system prompt changes.

  • State Reset: Reset the agent’s internal state without deleting your config: 
    hermes state reset
  • Disk Space: Ensure the drive containing the .hermes directory is not full, as this prevents the agent from writing to the state database.

🔄 Recovery Procedures

When standard troubleshooting fails, follow these recovery paths in order of intensity.

Level 1: Configuration Reset

If you suspect a configuration error but don’t know where, backup and reset:

  1. Rename current config: mv config.yaml config.yaml.bak
  2. Generate default config: hermes init
  3. Gradually migrate settings from .bak to the new file.

Level 2: Full Reinstallation

If binaries are corrupted or dependencies are irreconcilable:

  1. Uninstall the agent.
  2. Remove the global config folder: rm -rf ~/.hermes
  3. Re-run the installation script.
  4. Re-authenticate your providers.

Level 3: Backup Restore

If you maintain regular backups of your agent’s state:

hermes restore --backup-path ./backups/hermes_2026_07_10.tar.gz

❓ FAQ

Q: Why is my agent suddenly slower than usual? A: This is usually due to provider-side latency or an oversized context window. Try reducing the history_limit in your configuration to see if performance improves.

Q: Can I run multiple Hermes Agents on one machine? A: Yes, but you must specify different config directories using the --config-dir flag to avoid state conflicts.

Q: The doctor --fix command didn’t work. What now? A: Check the logs at ~/.hermes/logs/error.log. If the error persists, export your logs (redacting API keys) and open a ticket on the GitHub Issues page.

🔗 Companion Resources