Wiki · Start here
When something breaks
Most trouble has one of five causes — and the agent keeps its own record, so you can find out what happened.
🔧
Nothing breaks forever — and most trouble has one of five causes.
The agent keeps a record of what it did, so the first move is finding out what actually happened, and only
then changing something. Even things that looked hopeless got solved.
First three steps (in this order)
- Ask the agent what happened. You can write it straight into the conversation:
❯ Look through the log and find out what went wrong in the last step. ❯ Why did that command not run? What stopped it?The agent can read its own history and run output, so it often answers by itself and fixes it on the spot.
- Have the installation checked.
hermes doctorwalks the setup and reports what is missing or wrong:$ hermes doctor - Read the log and the conversation history.
$ hermes logs # what happened last $ hermes sessions browse # walk through past conversations
The five most common causes
| Symptom | Cause | Fix |
|---|---|---|
| Replies stop arriving, error 429 | Credit ran out, or you hit the provider's hourly limit | Top up, wait a while, or switch to a cheaper model (see choosing a model) |
| The agent says the context is too long | The conversation is longer than the model can hold | Trim it with /compress, or start a new one (/new) |
| No reply on Telegram or Discord, but the app works | The gateway that relays messages is not running | Check its status and start it again (see Telegram and Discord) |
| The model reports an invalid key | The key expired, was deleted, or its account is out of credit | Verify the key with the provider and enter a fresh one in the agent settings |
| The agent refuses to run a command | The command is dangerous (or on a deny list) and is waiting for your approval | Approve it, allow it permanently, or pick another approach (see security) |
When the agent answers oddly
| Symptom | What to do |
|---|---|
| An answer was cut off mid-way | Write "continue" — the agent picks up where it stopped. If it keeps happening, it is usually a weak connection or a small model |
| It mixes up context and drags up something old | Start a new conversation (/new). A long chat fills with irrelevant detail and the agent loses the thread |
| It claims something it cannot verify | Demand evidence: "Show me the file or command output you got that from." If there is no evidence, do not trust the claim |
| Answers are needlessly long | Say how you want them: "be concise, no tables" or "sum it up in five sentences first". The agent can save that to memory |
| Answers are slow | It is a large model or a long conversation. A smaller/faster model or a fresh chat helps |
What you can fix yourself
| Command | What it is for |
|---|---|
hermes doctor | Checks installation, settings, keys, what is missing |
hermes logs | The record of what happened (good to attach when asking for help) |
hermes sessions browse | Walk through past conversations and find what was done when |
hermes pause / hermes resume | Stop and restart all scheduled jobs |
hermes cron status | Whether the scheduler is alive — if not, jobs will not fire |
Where to get help
| Where | When to go there |
|---|---|
| Community Discord | The fastest route — ask others who have been through it |
| Official documentation | You need the exact wording of a setting or an error message |
| The official repository (GitHub) | A genuine bug in the software — that is where a report with steps belongs |
Before you ask for help, include: what you were doing, what you expected, what happened, and
the time. Where possible also the output of hermes logs. Without that the problem is hunted
blindly and the answer will be "try again".
Prevention that pays off
| What | Why |
|---|---|
Back up the ~/.hermes/ folder | Conversations, memory and skills live there — everything that cannot be found again |
| Keep secrets in the settings | So they never reach texts, backups or git (see security) |
| Change one thing at a time | Make three changes at once and something breaks, you cannot tell which one did it |
| Watch your usage | The most common reason for a sudden dead end is exhausted credit, not a bug |
| Know what is connected | Connections, skills and scheduled jobs are the three places surprises come from |
Where next
Frequently asked questionsAnswers to what people ask most⏳ coming soon
SecurityWhat the agent may do and what it must ask for
Scheduled tasksWhen a job does not fire, how to check it
Official documentationTroubleshooting in detail