Troubleshooting

Voice not working

Check stt.enabled: true in config.yaml
Verify provider: pip install faster-whisper or set API key
In gateway: /restart. In CLI: exit and relaunch.

Tool not available

hermes tools — check if toolset is enabled for your platform
Some tools need env vars (check .env)
/reset after enabling tools

Model/provider issues

hermes doctor — check config and dependencies
hermes auth — re-authenticate OAuth providers (or hermes auth add <provider>)
Check .env has the right API key
Copilot 403: gh auth login tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via hermes model → GitHub Copilot.

Changes not taking effect

Tools/skills: /reset starts a new session with updated toolset
Config changes: In gateway: /restart. In CLI: exit and relaunch.
Code changes: Restart the CLI or gateway process

web_extract shows a stale page (result caching)

web_search/web_extract cache results for 20 minutes (PR #94618) — a repeat fetch of the same URL within the TTL is served from cache, which can look like "my website changes aren't showing up."

Automatic carveouts (always fetched live, never cached):

localhost / 127.0.0.1 / *.local / *.localhost / single-label LAN hostnames / private + link-local IP ranges (dev servers, hot-reload builds, chat-GUI artifact previews)
URLs matched by security.website_blocklist
failed responses and keyless-rescue-served responses

Developing a site tested over the PUBLIC internet (Vercel/Netlify preview, ngrok/cloudflared tunnel, staging domain)? Public DNS isn't auto-carved-out — list the host in config.yaml:

web:
  cache_exempt_hosts:      # always fetched live; effective immediately
    - mysite.vercel.app
    - "*.ngrok-free.app"
    - mysite.dev           # suffix match: also covers preview.mysite.dev

Blunt instruments: web.cache_ttl_minutes: 1 (min) or web.cache_enabled: false disables both caches entirely.

Skills not showing

hermes skills list — verify installed
hermes skills config — check platform enablement
Load explicitly: hermes -s name (or the skill's own /<name> slash command)

Gateway issues

Check logs first:

grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20

Common gateway problems:

Gateway dies on SSH logout: Enable linger: sudo loginctl enable-linger $USER
Gateway dies on WSL2 close: WSL2 requires systemd=true in /etc/wsl.conf for systemd services to work. Without it, gateway falls back to nohup (dies when session closes).
Gateway crash loop: Reset the failed state: systemctl --user reset-failed hermes-gateway

Platform-specific issues

Discord bot silent: Must enable Message Content Intent in Bot → Privileged Gateway Intents.
Slack bot only works in DMs: Must subscribe to message.channels event. Without it, the bot ignores public channels.
Windows-specific issues (Alt+Enter newline, WinError 10106, UTF-8 BOM config, line endings): see references/windows-quirks.md.

Auxiliary models not working

If auxiliary tasks (vision, compression, session_search) fail silently, the auto provider can't find a backend. Either set OPENROUTER_API_KEY or GOOGLE_API_KEY, or explicitly configure each auxiliary task's provider:

hermes config set auxiliary.vision.provider <your_provider>
hermes config set auxiliary.vision.model <model_name>

"Reset permissions" / auto-approving everything

See references/security-privacy.md — wipe the "Always allow" stores, don't touch yolo mode.

3.6 KiB Raw Blame History