Fix Common Issues

Every complex tool has a rough edges phase. Hermes Agent is three months old and moving fast — v0.6.0 merged 95 PRs in 2 days. That velocity means occasional breakage.

This guide collects the real issues reported by real users in the Discord support threads and r/hermesagent, organized by category with the actual fixes. No fluff, no "try restarting" without specifics.

Token Issues

Token Overhead on Telegram (2-3x vs CLI)

The problem: Users reported 6-8K tokens per request via CLI but 15-20K tokens via Telegram gateway. That's a meaningful cost difference — 2-3x more expensive to access the same agent over Telegram.

Root cause (from Discord user kerichuu): The gateway was spawning in the hermes-agent repository directory and loading development context files — AGENTS.md from the repo, miscellaneous development data — none of which should be in a production session.

Fix: Update to the latest Hermes version. As of v0.6.0, the gateway starts in the user's home directory, not the repo directory. Run:

hermes self-update
hermes gateway restart

If you're on an older version and can't update: check that you're launching the gateway from ~ (home directory), not from the hermes-agent source directory.

Prevention: Run hermes config show | grep dir to verify the working directory. It should be your home directory.

High Token Usage on Simple Tasks

The problem: "21,000 tokens just asking about the weather" — a user reported this after Hermes spawned a terminal subprocess to run a weather command.

Root cause: Tool spawning adds token overhead. If Hermes decides to use the terminal tool for a simple query, you're paying for the tool definition overhead plus the execution.

Fix: For routine queries, be explicit: "Just answer this directly without spawning tools" or switch to a model with lower token costs (DeepSeek V4 or Kimi K2.5 for quick tasks).

Prevention: Set your cheap model (DeepSeek V4, Kimi K2.5) as the default and reserve Claude/GPT for complex tasks.

Token Costs Exploding Unexpectedly

The problem: "4 million tokens in 2 hours of light usage" — a real r/hermesagent post by u/Typical_Ice_3645. The root cause was a Telegram gateway debugging loop.

Fix:

1. Set API spend limits at your provider dashboard — all major providers (OpenRouter, OpenAI, Anthropic) have spend limit options
2. Check your gateway logs for loops: hermes gateway logs | grep -i error
3. Review your MEMORY.md — large memory files add tokens to every request

Community tool: u/Witty_Ticket_4101 built a token forensics dashboard at github.com/Bichev/hermes-dashboard that breaks down your token consumption by component.

Gateway Issues

Telegram Bot Not Responding

Step-by-step diagnosis:

1. hermes gateway status — is it running?
2. Check the bot token is correct in ~/.hermes/config.yaml
3. Verify your user ID is in allowed_user_ids in the Telegram config
4. hermes gateway logs — look for "unauthorized" or "thread not started"
5. Restart: hermes gateway restart

"Unauthorized user triggered thread" error: Fixed in PRs #4373 and #4387. Update Hermes to latest.

Bot can't see messages in group: The bot needs "Read Messages" permission in the group, or add the group ID (not user ID) to allowed_chats.

Discord Bot Not Responding

Checklist:

1. MESSAGE CONTENT INTENT is enabled in your Discord app's Bot settings (this is the most common cause of silent failures)
2. SERVER MEMBERS INTENT is enabled for reaction processing
3. Bot has been invited to the server with correct permissions
4. hermes gateway logs for Discord-specific errors

"Unauthorized users triggering threads": Same fix as Telegram — PRs #4373 and #4387. Update Hermes.

Gateway Not Starting After Reboot

Fix: Enable autostart on Linux:

hermes gateway enable-autostart

This creates a systemd service. Verify it worked:

systemctl status hermes-gateway

Security Module (Tirith) Issues

Commands Blocked Without Explanation

The problem: curl | sh and similar pipe patterns are blocked. The error message doesn't always explain why clearly.

Why it happens: Tirith blocks obfuscated shell patterns as a security measure — piped commands are a common injection technique. This is intentional and correct behavior.

The fix: Run trusted commands directly in your terminal instead of through the agent. If you need to run an install script:

# Download the script first
curl -fsSL https://example.com/install.sh -o install.sh
# Review its contents
cat install.sh
# Run it directly if you trust it
bash install.sh

Then tell Hermes the result. This gives you a review step before execution.

If Tirith is blocking legitimate commands: Check the Tirith config in ~/.hermes/config.yaml:

security:
  tirith:
    enabled: true
    block_patterns:
      - credential_exfiltration
      - prompt_injection

You can disable specific pattern categories, but understand the risk before doing so.

Model and Provider Issues

Local Models (Ollama) Lost Web Access

The problem: "It used to work perfectly before, but now the models behave as if they have no internet connection."

Why: Web tools require cloud model tool definitions to function. Local Ollama models don't have these built in — the web browsing capability depends on the model's native tool-use training, which varies by model.

Fix: Use cloud models (Kimi, DeepSeek, Claude) for web tasks. Local models are best for offline tasks: code generation, file operations, local debugging.

API Key Rejected

Common causes and fixes:

1. Whitespace in the key — copy/paste from dashboards sometimes includes trailing spaces. Re-copy directly from the provider.
2. URL-encoded characters — some providers return keys with %3D at the end. Decode it to = before pasting.
3. Wrong provider field — check you're setting the key for the right provider. OPENAI_API_KEY and ANTHROPIC_API_KEY are different.
4. Key expired or limits reached — check your provider dashboard.

Fallback Provider Not Triggering

The problem: Primary provider fails, but Hermes doesn't switch to fallback.

Fix: Configure the fallback chain explicitly in ~/.hermes/config.yaml:

providers:
  primary:
    type: openai
    model: gpt-5
  fallback:
    - type: anthropic
      model: claude-sonnet-4-5
    - type: minimax
      model: mini-max-2.7

As of v0.6.0, Hermes has a fallback provider chain feature. Update if you're not on the latest version.

"Command Not Found: hermes" After Install

Fix:

source ~/.bashrc        # Linux (bash)
source ~/.zshrc         # Mac (zsh)

Then verify: which hermes

If it still doesn't work, the installer may not have added Hermes to your PATH. Check the install script output or run:

export PATH="$HOME/.local/bin:$PATH"

Add that line to your .bashrc or .zshrc to make it permanent.

Memory and Skills Issues

Skills Not Appearing as Slash Commands

Diagnosis:

1. Skills must be in ~/.hermes/skills/ with a valid SKILL.md file
2. Run hermes skills check to validate installed skills
3. Check the skill has a valid frontmatter ---\nname:\n---\n format
4. Restart the session: hermes --fresh

Memory Not Persisting Between Sessions

Why this happens: Memory writes are saved to disk immediately but only injected into the system prompt at session start. If you make changes mid-session, they appear in the next session, not the current one.

To verify what's in memory: cat ~/.hermes/memories/MEMORY.md

To force a memory update: End the current session and start a new one. The updated memory will be loaded.

Session Search Not Finding Old Conversations

Fix: Sessions are stored in ~/.hermes/state.db. If the database is corrupted, Hermes may not find older sessions. To rebuild the search index:

hermes sessions reindex

This rebuilds the FTS5 index from the session database.

General Debugging Steps (Always Run First)

Before posting in Discord or opening a GitHub issue:

# 1. Check version
hermes --version

# 2. Check gateway status
hermes gateway status

# 3. Check recent logs
hermes gateway logs --tail 50

# 4. Restart gateway
hermes gateway restart

# 5. Update Hermes
hermes self-update

If opening a GitHub issue, include: Hermes version, provider/model, steps to reproduce, and relevant log excerpts (sanitize API keys first).

FAQ

Why is Hermes using more tokens on Telegram than CLI?

A bug in older versions had the gateway loading repo development files. Update to v0.6.0+ and restart the gateway.

How do I stop Tirith from blocking my commands?

Tirith blocks patterns, not commands. Run trusted commands directly in your terminal. If you need to run a piped command, download and review it first.

My bot isn't responding on Discord/Telegram. What do I check first?

1. Gateway running (hermes gateway status)
2. Correct bot token in config
3. Your user ID in allowed list
4. MESSAGE CONTENT INTENT enabled (Discord)
5. Restart gateway

Can Hermes recover from a runaway loop?

Yes — interrupt with Ctrl+C in the terminal. For gateway loops, hermes gateway restart breaks the cycle. Set API spend limits at your provider to prevent runaway costs.

Setup Guide | Token Overhead | Gateway Setup

flyhermes.ai