Skip to main content
✦HERMINA · YOUR PERSONAL HARNESSExplore
HERMINA
ENPT
Get Started
Docs/Troubleshooting

Troubleshooting

Diagnose Hermina from the outside in: network, management API, agent runtime, model, channel policy, and finally automation. Changing several layers at once makes the original failure harder to identify.

Recovery order

Run these checks in order:

hermina angels status
curl -fsS http://127.0.0.1:3456/health
hermina status
hermina list
hermina logs <agent> --lines=100
hermina model <agent>
hermina bridge <agent>

Then test a plain dashboard message. Only after that works should you test WhatsApp, Telegram, Matrix, tools, queues, or cron delivery.

Client cannot connect

Symptoms

  • Login times out.
  • Health works on the server but not on the client device.
  • Pairing code is rejected.
  • WebSocket shell fails while normal pages work.

Checks

  1. Open <server-url>/health from the client device.
  2. Replace 127.0.0.1 with a reachable private/VPN address for remote clients.
  3. Generate a new code with hermina connect --code.
  4. Verify the key exists with hermina angels key.
  5. Inspect hermina angels logs --lines=100.
  6. Confirm the proxy preserves Authorization and WebSocket upgrade headers.
  7. Check firewall, TLS certificate, and CORS only after basic routing succeeds.

Agent will not start

hermina logs <agent> --lines=150
hermina build <agent>
hermina restart <agent>

Common causes include:

  • Missing Docker image.
  • Invalid YAML or environment values.
  • Host port conflict.
  • Stale container definition after a webhook-port change.
  • Missing profile files or incorrect permissions.
  • systemd failure for a host-based angel.

Do not repeatedly recreate the agent before copying its profile data. Logs normally identify whether the failure happens in the queue wrapper, channel bridge, or Hermes Gateway.

Model fails or returns no useful answer

hermina model <agent>
hermina logs <agent> --follow

Verify:

  • The correct key exists in the agent's .env.
  • The provider and model name match the account.
  • The base URL includes the expected API path.
  • The selected API mode matches the endpoint.
  • A local model is reachable from inside the container.
  • The model supports a sufficient context window and tool calling.

Test with a simple prompt that does not require tools. If that works, test one tool at a time.

WhatsApp is disconnected

hermina bridge <agent>
hermina logs <agent> --follow
hermina qr <agent>

If no valid session exists, restart the agent and scan the new QR from the agent account's Linked devices screen. Preserve agents/<name>/whatsapp/session/ across updates.

If the bridge is connected but the bot ignores a user, inspect allowlist, group, and slash-command policy rather than re-pairing:

hermina allowlist <agent>
hermina groups <agent>
hermina commands <agent>

Send /whoami and use the exact returned identifier. WhatsApp LID identifiers can differ from the visible phone number.

Telegram or Matrix ignores groups

For Telegram, check mention-only mode:

hermina telegram-groups <agent>

For Matrix, confirm allowed users, allowed rooms, and require_mention. Also verify the bot account has joined the room and that its access token is valid.

Queue is stuck

hermina queue health <agent>
hermina queue list <agent>
hermina queue logs <agent> --lines=100

The agent container must be running. A task can remain pending when the worker is unhealthy; it can remain processing when the worker stopped during execution. Inspect the task and worker logs before manually changing the SQLite database.

Cron job did not run or deliver

hermina agent-cron <agent> list

Check:

  • The job is not paused.
  • The schedule and server timezone match your expectation.
  • The agent runtime and model were available at execution time.
  • Required tools and credentials still work.
  • The delivery channel is connected.
  • Inbox or execution history contains a result even if delivery failed.

Configuration change appears ignored

  1. Confirm you edited the intended agent and server.
  2. Restart the agent after a direct file edit.
  3. Inspect the effective values with the task-specific CLI command.
  4. Check logs for YAML parse errors or compatibility overrides.
  5. Make sure another client did not write stale configuration at the same time.

For container agents, remember that the persistent host profile is mounted at /root/.hermes inside the container.

Collect a useful issue report

Include:

  • Hermina commit or installed version.
  • Operating system and installation path.
  • Agent runtime type: container or angel.
  • Exact command or UI action.
  • Expected and actual behavior.
  • Relevant log excerpt with secrets removed.
  • Whether dashboard chat, channel messaging, and other agents still work.

Never include API keys, provider tokens, authorization headers, connection QR contents, .env, or WhatsApp session files in an issue.