Hermes Agent Gateway Troubleshooting: Fix a Bot That Is Not Replying

A Hermes Agent gateway can look healthy while Telegram, Discord, or another channel stays silent. “Connected” only proves that the platform adapter started. It does not prove that the message passed the allowlist, reached the right profile, completed a model turn, and returned to the same chat or thread. The Hermes Agent Dashboard can expose profile, session, log, and gateway evidence; only a reply in the exact destination proves end-to-end recovery.

Windows PermissionError in gateway-locks: check local access first#

If a Discord gateway fails with PermissionError: [Errno 13] Permission denied and the path contains gateway-locks, investigate the local lock directory before rotating the bot token or moving your Hermes installation. A filesystem permission error is not the same as Discord rejecting a credential.

The official profile documentation explains that Hermes blocks a second gateway when profiles reuse a supported platform's bot token. That protection needs a lock shared across profiles. A lock outside a particular profile's home is therefore not, by itself, evidence of profile drift.

Distinguish three failures that need different repairs#

• Permission denied opening or creating the lock: the operating-system account cannot access the indicated directory or file. Inspect Windows ownership and permissions.
• A lock-conflict error names another profile: establish which live gateway owns the bot. Stop only the confirmed unintended consumer through its service manager; do not remove the lock as a shortcut.
• The adapter connects, but the model turn fails: the token lock is no longer the first failing layer. Check the provider response, local-model server, context capacity and the same profile's model configuration.

Use the exact error and timestamp to choose a branch. A stale lock filename, a missing file, and an inaccessible directory are different observations. Deleting a file cannot fix a parent directory that the service account cannot enter.

Inspect Windows permissions without changing them#

Run these read-only checks in an ordinary PowerShell window under the account that normally runs Hermes. The directory below is the one observed in the support case; if your error prints a different directory, inspect that exact path instead of creating this one.

whoami
$lockDir = Join-Path $env:USERPROFILE '.local\state\hermes\gateway-locks'
Get-Item -LiteralPath $lockDir -Force |
  Select-Object FullName, Attributes
Get-Acl -LiteralPath $lockDir |
  Format-List Owner, AccessToString
icacls $lockDir

An access-denied result is useful evidence. Do not interpret a blank Owner column in Explorer as proof that the folder has no owner: the account may simply lack permission to read its security descriptor. A machine administrator can inspect the same path with an elevated shell and compare the effective account with the account used by the service.

Before any repair, record the current ACL and intended service identity. Ask the administrator to grant only the required access to that identity on the affected directory, preserving a permissions backup and rollback path. Do not grant Everyone full control, recursively change your entire home directory, or keep Hermes running as Administrator just to hide the failure. This guide deliberately does not supply a universal ACL-reset command: inherited permissions and service identities differ between machines.

If the error instead names another live profile, follow the profile ownership checks. A named profile separates Hermes configuration and state; it is not a Windows account or a filesystem sandbox. The server security guide covers the broader operating-system boundary.

Verify the repair from the normal runtime account#

Replace work with the existing profile that owns the Discord bot. These commands do not create a profile or move its files:

hermes -p work config path
hermes -p work config env-path
hermes -p work gateway status

Once the permission or ownership issue has been corrected, restart that owning gateway from a separate terminal, not from the failing bot conversation. Use hermes -p work gateway restart only after checking the intended service and outstanding work. Then send one harmless message in the exact Discord channel or thread and correlate the new log window with the reply. The Discord setup guide covers channel permissions and message routing; those are separate from a local Windows ACL.

If the adapter now connects but the reply still fails, stop repeating the filesystem repair. Run a bounded model test under the same profile, inspect its provider error, and check the inference server's actual context setting. Raising a configuration number does not give a model or GPU unlimited capacity. Use the provider diagnostic guide for credential/quota failures and the memory and context guide for context failures.

What the October support case does and does not prove#

An October 2, 2026 Discord support thread initially looked like a wrong-install-directory problem. The thread reported an ACL that allowed administrators and SYSTEM but did not give the ordinary runtime account the needed access. After a targeted permission repair, the connection returned. The user then reported a separate local-model context-setting issue before confirming replies worked.

That is one reported recovery, not a reproduction on our test machine or a universal diagnosis for every Windows install. It illustrates why “bot connected” and “agent answered” need separate acceptance checks. Do not copy the case's model context size as a default for your own model.

The self-hosted Hermes Dashboard is a configuration and monitoring checkpoint, not proof that a Discord message completed. If maintaining accounts, services and recovery procedures is the recurring burden, compare self-hosted and hosted Hermes and the managed hosting option. Managed hosting changes infrastructure ownership; it does not remove your responsibility for bot permissions, recipients or model usage.

A cron delivery failure does not require another agent run#

Current Hermes records delivery_failed and last_delivery_error when scheduled execution succeeds but sending lacks positive delivery evidence. The execution failure streak does not increase for that case. Inspect the saved artifact before changing the provider or triggering the whole job again.

Check the exact destination, bot membership, thread permissions, active profile, and platform error. If a timeout leaves send status uncertain, read back the destination first. Recover or redeliver the existing report where supported rather than repeating a workflow that may already have published or modified external records. The cron delivery recovery guide owns the safe-rerun decision; gateway connectivity alone is not delivery proof.

Source: official Hermes scheduled-task documentation.

Gateway triage before changing configuration#

Run these commands from a normal terminal on the machine that hosts the gateway:

hermes doctor
hermes chat -q "reply with gateway-smoke-test"
hermes gateway status
hermes status --all
tail -160 ~/.hermes/logs/agent.log
tail -160 ~/.hermes/logs/errors.log

For a named profile, add -p <profile> to the Hermes commands:

hermes -p support-bot chat -q "reply with ok"
hermes -p support-bot gateway status

Use the Hermes Dashboard and Web UI to inspect profiles, sessions, providers, cron jobs, and gateway state, but do not treat a green dashboard as end-to-end proof. hermes dashboard is the backend plus browser UI; hermes serve is the headless remote-Desktop backend; neither replaces the messaging gateway. Finish with one real message in the exact destination that failed.

Diagnose the symptom before changing anything#

The bot is online but never receives the message#

This is usually a platform or gating failure:

• the human sender, group, guild, or channel is not allowed;
• Telegram privacy or mention rules suppress the message;
• the Discord bot lacks message-content intent or channel/thread access;
• the message was sent to a forum topic or thread that is not configured;
• a network or proxy problem prevents the adapter from reaching the platform API.

Look for the inbound message in ~/.hermes/logs/agent.log. If no matching update appears, changing the model will not help.

The inbound message appears, but no agent turn starts#

Inspect allowlists, mention gating, topic/thread routing, and the active profile. The token may be valid while the human sender is still unauthorized. The Telegram setup guide explains user IDs, chat IDs, and forum topics; the Discord setup guide covers intents, permissions, and threads.

The agent turn starts, then fails#

Search the logs for provider errors, exhausted credits, timeouts, compression failures, or tool exceptions. A connected gateway can still fail every reply because the selected provider or auxiliary model cannot complete the turn. Test the same profile with hermes chat -q and use the provider fallback guide if the failure follows the model route.

The bot replies twice#

Assume duplicate gateway processes before blaming Discord or Telegram. A recent community case had both the current launchd service and a stale legacy profile service handling every Discord message. Check the deep status and process list:

hermes gateway status --deep --full
ps -axo pid,ppid,lstart,command | grep -E '[h]ermes.*gateway|[p]ython.*gateway'

On macOS, also inspect loaded Hermes launchd jobs:

launchctl list | grep -i hermes

Restart all managed gateway processes from a normal terminal:

hermes gateway restart --all

If a stale legacy launchd job immediately respawns, unload that specific legacy service instead of repeatedly restarting the current one. Do not kill processes blindly until you have identified which profile and service each PID belongs to.

The service says running, but every channel is silent#

A supervisor can be alive while the agent loop is stale, the child process is crash-looping, or an old process still has pre-update code in memory. Restart the gateway service—not only the chat session—and inspect fresh log timestamps:

hermes gateway restart
hermes gateway status --deep --full
tail -160 ~/.hermes/logs/agent.log

Use hermes gateway run --replace for a foreground recovery when you need to replace a stale process and watch startup output directly. Keep that terminal open while testing.

Telegram bot connected but not replying#

Telegram has separate identity and routing layers. Verify each one.

1. Distinguish the bot ID from the human user ID#

The numeric prefix in a bot token identifies the bot. It is not your personal Telegram user ID. If logs say blocked unauthorized user, use the human sender ID in the effective allowlist. Current configuration supports sender and group scopes such as allow_from, group_allow_from, and group_allowed_chats.

Do not print or paste the bot token while debugging. Use /whoami or the gateway's pairing/authorization flow where appropriate, then restart the correct profile's gateway after changing configuration.

2. Test the exact destination#

A parent-group test does not prove a forum topic works. Verify:

• the supergroup chat_id;
• the topic's message_thread_id;
• require_mention behavior;
• free-response topic or chat settings;
• group sender/chat allowlists;
• that the bot can read and send in that topic.

A private t.me/c/... link contains a group and message reference, not enough information by itself to prove the thread ID. Use current logs or the channel directory to confirm the actual routing values.

3. Check for network-specific Telegram failures#

If several Telegram bots fail while Discord and internal cron jobs keep working, test access to api.telegram.org from the gateway host. A July 2026 community incident traced silent Telegram bots to a network path that timed out against Telegram's API. Hermes supports an HTTP, HTTPS, or SOCKS5 Telegram proxy:

hermes config set telegram.proxy_url socks5://127.0.0.1:1080
hermes gateway restart

You can also use TELEGRAM_PROXY in the correct profile environment. A proxy is a network workaround, not a fix for wrong user IDs or topic routing.

For a complete first-time setup, use Connect Telegram to Hermes Agent. For incident recovery, keep following this page.

Discord bot online but not responding#

Discord's online indicator is not proof that Hermes can read and answer in the target location. Check:

• Intents: enable the intents required for ordinary message handling.
• Permissions: verify read, send, message-history, and thread permissions in the target channel.
• Allowlist policy: confirm the human user, role, or channel is authorized.
• Mention rules: test both an explicit mention and the intended free-response path.
• Threads: verify access to the parent channel and the exact active thread.
• Duplicate processes: two gateways can generate two different replies to one message.

If the CLI works and the logs show no inbound Discord message, stay on Discord permissions, intents, or channel gating. If the inbound message appears and the model turn fails, move to provider or tool diagnostics.

The Discord integration page explains the product boundary; Connect Hermes Agent to Discord covers first-time configuration.

Profile drift: the gateway is running the wrong configuration#

Hermes profiles isolate config, .env, sessions, memory, skills, and gateway services. That isolation is useful, but it creates a common failure mode: you fix the default profile while the production bot runs under another profile.

Check the profile explicitly:

hermes profile list
hermes -p support-bot config path
hermes -p support-bot config env-path
hermes -p support-bot gateway status

Desktop remote-gateway settings can also be scoped. A community case showed new Desktop profiles inheriting a local gateway because the remote URL was saved only for one named profile rather than “All profiles.” Verify which host each profile targets before changing remote files.

Read the Hermes Agent profiles guide before sharing one bot, secret set, or memory boundary across unrelated projects.

Remote gateway and Desktop problems#

Hermes Desktop, the self-hosted Dashboard, the optional OpenAI-compatible API server, and messaging gateways are adjacent but separate surfaces:

• Desktop Remote Gateway and the Dashboard use the dashboard backend, normally on port 9119.
• The optional OpenAI-compatible API server normally uses port 8642.
• Telegram, Discord, Slack, and other adapters run through profile-specific gateway services.

A working Desktop connection proves the control plane is reachable. It does not prove that Telegram or Discord can receive and send in a target thread. Conversely, a port collision on 8642 can crash a profile's child process while the supervisor remains visible.

For remote setups, use the Desktop remote backend guide and keep the Dashboard private behind localhost, SSH, Tailscale, or an authenticated HTTPS reverse proxy.

Restart safely on macOS, Linux, and Docker#

macOS launchd#

Use the Hermes service commands first:

hermes gateway restart
hermes gateway status --deep --full

If a reduced service PATH prevents standard binaries from resolving, retry with an explicit macOS path:

PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes gateway status --deep --full

Do not trust launchd state alone; test a real channel message after recovery.

Linux systemd#

For a user service, inspect both Hermes and systemd:

hermes gateway status
systemctl --user status hermes-gateway
journalctl --user -u hermes-gateway -n 160 --no-pager

Run a restart from SSH or a normal shell outside the gateway process. A gateway cannot safely replace itself from inside the active agent turn in every environment.

Docker and s6#

Confirm that the CLI test and gateway use the same mounted HERMES_HOME, profile, .env, and provider credentials. Current official container supervision keeps per-profile gateway state and logs; a container can restart while preserving the intended running/stopped state. Inspect the Hermes Docker troubleshooting guide before rebuilding volumes or deleting state.

Use logs as a timeline, not a keyword dump#

Read log timestamps around one controlled test message. Look for this sequence:

1. platform connected;
2. inbound message received;
3. authorization/gating decision;
4. agent turn started;
5. provider/model response or error;
6. outbound send success or failure.

Current gateway activity is commonly visible in ~/.hermes/logs/agent.log; gateway.log can be stale depending on how the service was launched. If support needs a reproducible bundle, create a redacted debug report:

hermes debug share --lines 500

Review the report before sharing it. Never paste raw .env files, bot tokens, provider keys, or private conversation content into a public issue.

What counts as fixed#

Do not close the incident because the Dashboard loads or the adapter says connected. Require all of these:

• hermes doctor passes under the gateway profile;
• hermes chat -q "reply with ok" completes under that profile;
• hermes gateway status --deep --full shows the intended service and profile;
• fresh logs show the controlled inbound test;
• the exact Telegram DM/topic or Discord channel/thread receives one reply;
• no duplicate process produces a second reply;
• the next restart or host reboot preserves the healthy state.

When managed hosting is the better answer#

Self-hosting is the right choice when you want full control over files, models, tools, and network boundaries. It is still an operations commitment: provider credits, bot permissions, Docker or systemd, updates, logs, backups, remote access, and incident recovery remain yours.

If the real requirement is “reach my agent reliably from a browser or phone” rather than “operate an agent server,” compare self-hosted versus hosted Hermes and the managed FlyHermes path. FlyHermes is the hosted browser/mobile/channel experience; the self-hosted Dashboard remains the configuration and monitoring surface.

Prove delivery while the client is closed#

A connected gateway status is not proof of an always-on workflow. Send one real message to the exact chat or topic, schedule one harmless follow-up, close Desktop, and verify the runtime delivers without manual intervention. If the agent lives on a laptop, sleep ends the test; the self-hosted vs hosted guide explains the always-on ownership boundary.

If the gateway is spending on the wrong model#

Treat unexpected provider spend as an incident, not as a normal “bot not replying” retry loop. Restrict the affected channel or pause its scheduled work, capture the active profile/provider/model and usage window, then inspect gateway logs and config history before reauthenticating. Restart the owning gateway only after restoring the intended route, and verify one real message plus provider usage. The provider cost and rate-limit guide has the full stop, preserve, cap, and re-enable sequence.

A working fallback reply does not prove the primary recovered#

When inbound transport works but a turn hits a provider limit, inspect the model route used for the eventual answer. A backup may keep the conversation alive while the original provider remains in a quota cooldown. Expiry only makes another primary attempt eligible; it does not schedule a test or guarantee success.

Capture the inbound message timestamp, primary error, pool/fallback decision, and outbound reply in the exact chat or thread. If a model response exists but delivery failed, retry delivery only after checking whether it already arrived; do not repeat an externally mutating agent task blindly. The provider fallback setup and verification guide provides the provider-side checks. Bot-token rotation cannot repair a provider's billing or reset window.

Source: official Hermes fallback and recovery documentation, checked October 1, 2026.

Prove the model route before rotating bot tokens#

When Telegram or Discord receives updates but no answer arrives, run one CLI smoke test under the gateway's exact profile. A 401, 402, 403, 429, or output-limit error means the messaging transport may be healthy while the model route is not. Fix the provider lane with the Hermes cost and rate-limit decision tree, restart the gateway to reload config, then send one real message in the target chat or thread.

A gateway chat may have a different browser lane#

/browser connect is an interactive-CLI command, not a Telegram, Discord, or Web UI command. Browser Use mode also requires terminal access. If a browser task works locally but fails through a gateway, compare toolsets and the effective driver before changing bot credentials; use the browser troubleshooting guide for the real-profile and CDP decision.

Telegram delivery after a gateway restart#

Current Hermes records unfinished platform responses in a delivery ledger. A recovered Telegram reply may be labeled as a possible duplicate because delivery is at-least-once. Reconcile external side effects before retrying, then use the Telegram setup and topic-routing guide to verify the exact DM, group, or thread.

Separate cron execution from gateway delivery#

A cron agent can finish while the gateway fails to deliver its result. Inspect hermes cron runs <job> --limit 20, local output, and last_delivery_error; then test the exact chat, topic, or channel. The cron failed-runs guide explains why delivery errors, unknown attempts, and intentionally silent ticks require different recovery actions.

Use Dashboard as evidence, then test the channel#

The Hermes Dashboard helps identify the selected profile, gateway state, provider usage, logs, automation sessions, and resource pressure. It is still a checkpoint: a green card or successful browser Chat does not prove Telegram, Discord, Slack, or cron delivery. After diagnosis, send one test in the exact target chat, topic, or channel and match it to the same gateway log window.

Assign gateway incident ownership before production#

For a self-hosted agent, someone must notice and repair duplicate polling, stale processes, topic routing, permissions, provider completion, and failed delivery. The hosted versus self-hosted responsibility matrix separates platform uptime from the customer's continuing responsibility for recipients, permissions, and consequential actions.

A connected gateway can still have a wedged browser worker#

Gateway connectivity proves message transport, not browser completion. After a Chrome or host restart, an old browser harness can keep accepting socket connections while pointing at a dead CDP endpoint. The browser automation recovery guide gives a harmless public-page test and targeted restart sequence before the real channel workflow is retried.

Fix “Gateway is shutting down and is not accepting another turn”#

This message is different from a bad bot token. Hermes has entered its drain state: it is refusing new work while an old turn or restart is supposed to finish. On macOS, launchd may still report the service as running and gateway_state.json may still say the platform is connected even though the in-memory agent loop never returned to an accepting state.

Use a layered check instead of trusting one green indicator:

1. Run hermes gateway status and note the reported service state.
2. Inspect ~/.hermes/gateway_state.json for draining, platform state, and update time.
3. Read the current tail of ~/.hermes/logs/agent.log for shutdown, drain-timeout, suspended-turn, or restart errors.
4. On macOS, inspect the actual service with /bin/launchctl print gui/$(id -u)/ai.hermes.gateway.
5. Compare the gateway PID with the process that launchd owns. A stale wrapper can exist while the healthy-process check says “not running.”

If the evidence shows a wedged drain rather than a busy turn, perform a full service restart from a separate shell. Do not issue a restart from inside the same gateway turn: terminating the parent process can also terminate the repair command before the service returns. After recovery, verify an actual reply in the exact destination—not merely connected in a state file.

macOS launchd recovery when launchctl or bash is “missing”#

A gateway launched from a menu app, cron, or LaunchAgent can inherit a reduced PATH. That creates confusing failures such as FileNotFoundError: launchctl during status checks or No such file or directory: 'bash' during a detached restart even though both programs exist on macOS.

First prove the binaries with absolute paths:

/bin/launchctl print gui/$(id -u)/ai.hermes.gateway
/bin/bash --version

Then run the Hermes command from a separate terminal with a complete standard path:

PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" hermes gateway status

If the installed LaunchAgent definition is stale or unloaded, use hermes gateway install or hermes gateway start from that external shell, then re-check the service and current agent log. Do not repeatedly reinstall while a previous gateway is still draining; preserve the current plist and logs before replacing service state.

Prove Telegram forum-topic delivery end to end#

A successful Telegram DM does not prove a forum topic works. Topic delivery also depends on the correct supergroup ID, message_thread_id, mention policy, free-response configuration, bot privacy mode, and whether the gateway received the update at all.

For a failed topic message:

1. Confirm the group and topic appear in ~/.hermes/channel_directory.json.
2. Send a new controlled message after the gateway is healthy; messages sent while polling was offline may not be available after reconnect depending on update-drop behavior.
3. Search the current agent log for the exact chat ID and for mention, allowlist, thread, ignored, or skipped decisions.
4. Verify telegram.require_mention, telegram.free_response_chats, and topic-specific configuration under the active profile.
5. Test a reply in the exact topic. A plain chat_id send proves group access, not thread routing.

When one topic must stay dedicated to a project, use a topic-specific channel prompt and register the topic metadata. Current-topic instructions should outrank cross-project memory or session search, so a working gateway does not become a context-leak path.

Recovery acceptance test#

Do not close the incident at “service running.” A recovered gateway should pass all of these checks:

• one CLI model smoke test under the gateway profile;
• one current agent.log inbound event for the test message;
• one completed model turn without provider or auxiliary-route failure;
• one reply in the exact DM, topic, channel, or thread;
• no duplicate reply from a second poller;
• no lingering draining or shutdown state;
• one scheduled-delivery check if cron output uses the same gateway.

If maintaining this chain is the recurring problem rather than a one-off incident, compare the operational responsibility with managed FlyHermes and the self-hosted versus hosted responsibility matrix.

Dashboard reachability is a separate layer#

A gateway can be healthy while the Hermes Dashboard localhost route is down, and the dashboard can be green while Telegram or Discord delivery is broken. Recover 127.0.0.1:9119 through the process/port/assets/profile/WebSocket ladder, then return to the exact channel test. Do not rotate a bot token merely because the browser control plane is unavailable.

Rule out Dashboard release skew#

If gateway controls or logs look different from the CLI, use the Dashboard version-mismatch runbook before changing channel credentials. An old dashboard process can display stale capabilities while the profile gateway remains healthy. Verify the exact profile, then test the real destination.

Do not delete SQLite sidecars during gateway recovery#

A gateway can be connected while its profile session store is unhealthy. If logs show DeletedWalGenerationError, session storage unavailable, or a malformed database, use the session-storage recovery decision tree. Update and reopen cleanly first; never delete state.db-wal or state.db-shm under a live process.

If a Telegram or Discord turn starts but only the browser step fails, prove the browser lane independently. Test one public page through the configured Tool Gateway, Browser Use CLI, or local backend before restarting the messaging gateway again; the browser troubleshooting guide has the exact split.

Discord delivery ownership#

If Discord produces duplicate replies, inspect process ownership before prompt or provider settings: one bot token should have one active gateway consumer. Use the Discord integration incident ladder to map one test message from inbound event to exactly one reply.