Optional deep dive · Troubleshooting
Every nurse has had a shift go sideways — and every Hermes user eventually has a day where nothing responds, something looks broken, or a file isn't where it should be. None of that is an emergency, and none of it means you did something wrong. This page is how to approach it: assess first, one intervention at a time, and know exactly when to escalate.
1The triage mindset
You already know how to do this. When a patient deteriorates, you don't try five interventions at once and hope — you assess, you act on the most likely cause, you reassess. Broken software responds to exactly the same discipline.
Ask "what changed last?" Most breakage follows a change: an update, a new setting, a new provider key, a new skill. The last thing you changed is the first suspect.
One change at a time, then reassess. If you flip four settings and it starts working, you don't know which one fixed it — or which of the other three will bite you later. Titrate.
Chart as you go. Keep a scratch note of what you tried and what happened. It keeps you from repeating steps, and it becomes your report if you need to ask for help.
The escalation ladder
Work up this ladder in order. Most problems never make it past the second rung.
2First response checks
Before diagnosing anything exotic, check the basics — in order, like any primary survey.
| Check | What to look for |
|---|---|
| A · App | Is Hermes actually running, and current? Quit fully and reopen. Check the About screen — if an update is waiting, take it (release notes tell you what changed). |
| B · Backend | Is the gateway alive? If chats won't start at all, open Settings → Gateway and use Open logs — the last few lines usually name the problem. On a remote gateway, test the connection. |
| C · Connection | Internet up? Provider working? A surprising number of "Hermes is broken" days are actually a provider outage, an expired key, or a spending limit quietly reached. Check your provider's status page and your account's billing/credits. |
If Hermes is responding but acting strangely — wrong folder, weird command behavior — remember the persistent shell from the configuration handbook: the terminal remembers its last setup, and the handoff may be stale. A new session clears it, or ask Hermes directly: "Check what directory you're in and what's active before we continue."
3Describe the problem
The hardest part of getting help — from a chatbot, a forum, or a friend — is describing the problem well. You already own the best tool for that. Give SBAR to a technical problem and helpers can actually help.
| SBAR | For a tech problem, that means |
|---|---|
| S · Situation | What were you doing, and what happened? "I asked Hermes to edit a file and it froze with a spinning icon." |
| B · Background | What changed recently? Updates, new settings, new providers, new skills. "This started after yesterday's update. I also added a new API key last week." |
| A · Assessment | The exact error message, word for word (or a screenshot). Does it happen every time or only sometimes? Only in one chat or all of them? |
| R · Request | What do you want? "Explain what this error means, then give me the smallest, safest next step — one step at a time." |
Write your SBAR once and it works everywhere: pasted into a chatbot, posted in a community, or handed to the tech-comfortable friend who asks "okay, what exactly happened?"
4The screenshot method
This is the troubleshooting path for everyone. Modern chatbots read screenshots well — an error message you don't understand is an error message you can photograph.
A prompt that works. Copy this, adjust the brackets, attach your screenshot:
5The terminal, if you know how
Entirely optional — if the terminal isn't your comfort zone, the screenshot method above does the job and you can skip to chapter 7. If you're willing to open Terminal (Mac) or PowerShell (Windows), these four commands are the whole troubleshooting kit.
| Command | What it does |
|---|---|
| hermes status | The vital signs: a quick visual overview of your install — what's running, what's connected. |
| hermes doctor | The head-to-toe assessment: checks configuration and dependencies and reports findings. Chapter 6 is how to read it. |
| hermes logs | The chart: views and follows Hermes' log files, where errors explain themselves. The last lines before a failure are the interesting ones. |
| hermes update --check | Asks whether a newer version exists without installing it. Drop the --check to actually update. |
And when you need to show someone your setup, hermes dump prints a compact, copy-pasteable summary designed for exactly that — version, model, which keys are set (as set / not set, not the keys themselves), gateway status. It's the hand-off sheet for your install.
6Reading the assessment
Run hermes doctor and Hermes examines its own install — configuration, dependencies, connections — then reports findings. It looks technical. It reads exactly like an assessment sheet.
Doctor output is a list of individual checks. Sort them the way you'd sort assessment findings:
| Finding type | What it means | What to do |
|---|---|---|
| Passing checks ✓ | Within normal limits. | Nothing. Don't let a long list of passes intimidate you — that's a healthy chart. |
| Warnings ⚠ | Chronic conditions: not what's hurting you today, but worth noting. Often version or configuration nags. | Note them. Address when convenient. |
| Errors / failures ✗ | Acute findings: missing dependencies, broken config, a provider that can't authenticate. | These are your problem list. Treat these — usually the first one first, since later failures often cascade from it. |
Exact checks change between versions, but failures tend to fall into families: a version that's behind (fix: update) · an API key or provider that's missing, expired, or out of credit (fix: reconnect in Settings → Providers) · a gateway that isn't running (fix: restart Hermes, then check gateway logs) · a config file problem or missing dependency (fix: let doctor try, or escalate to chapter 7).
hermes doctor --fix attempts automatic repairs where possible. It's reasonable to let it — that's what it's for — but read what it says it did afterward, and re-run plain hermes doctor to confirm the finding cleared. One intervention, then reassess.
And if the output might as well be another language? You already know the move: screenshot or copy the whole output, paste it into a chatbot with your SBAR, and ask: "Explain each finding in plain language. Which one is most likely causing [my problem]? Smallest safe step first."
7Setting up again
When the ladder's lower rungs haven't worked, or the install feels deeply tangled, you rebuild. The important thing to know: rebuilding is routine, not defeat — and it almost never has to cost you your data.
Copy your working folder (your My-Nurse-AI-OS folder) somewhere safe — an external drive or your cloud drive. Know where your provider accounts live (you'll reconnect with a login or a fresh key — you never need to have "saved" the old key). Two minutes of packing before any demolition.
Advanced note: if you ever made a Hermes backup zip, hermes import <backup.zip> restores it — it overwrites current config, so it's a deliberate act, done with the gateway stopped.
8Protecting your files
Sometimes a file gets deleted that shouldn't have been — by a tool call that went wide, an approval clicked too fast, or plain human error. Two halves to this: the protection you set up before, and the calm sequence you follow after.
Prevention
| Layer | What it protects |
|---|---|
| 1 · The assigned unit | Working directory scoped to one folder (handbook ch. 1). Hermes can't delete what it never reaches. |
| 2 · File Checkpoints ON | The before photo (handbook ch. 4). Hermes snapshots files before edits — and the in-session /rollback command restores them. |
| 3 · Smart approvals, actually read | Deletions should always ask. When an approval prompt contains the words delete, remove, or rm — stop, read it twice, and make sure you know exactly which files it means before approving. |
| 4 · Real backups | Time Machine (Mac) or File History (Windows) covering your working folder, or a cloud-synced folder with version history. This is the layer that saves you when everything else didn't. |
| 5 · The two-copies rule | Anything you'd grieve — course work, your SOUL file, months of notes — exists in at least two places. A file that exists in one place is one accident away from existing in none. |
Recovery
9Escalation
On a unit, the nurse who asks early looks better in the morbidity review than the one who soldiered on. Same here.
The official FAQ & troubleshooting docs first — your problem is probably in there. Then the Hermes community (Discord, GitHub issues). And bring recurring or gray-area problems to the monthly Lamp Huddle — if it happened to you, it's happening to other nurses.
Your SBAR, the exact error text or a PHI-checked screenshot, and — if you're terminal-comfortable — the output of hermes dump, which was built for exactly this and shows whether keys are set, never the keys themselves. A well-packaged question usually gets answered in minutes.
And a closing word: a Hermes that misbehaves is an inconvenience, not an incident — the perimeter is what keeps mistakes small. No PHI in the system means no PHI in the error message, the screenshot, the logs, or the support thread. Keep the perimeter, and every problem on this page is just a fixable, forgettable Tuesday.
Companions to this page: Understanding Hermes Configuration — The Handbook (the settings this page keeps pointing at) · the one-page cheat sheet · Start Here if you're rebuilding from scratch.
The safety perimeter
Do not enter patient names, charts, screenshots, identifiers, room numbers, employer secrets, passwords, account numbers, or patient-specific clinical details into Hermes, the quizzes, dashboards, or any AI tool — unless an approved institutional environment and accountable governance explicitly allow it. That includes troubleshooting: check every screenshot before it leaves your screen, and never paste secrets into a support thread.
Hermes can help with learning, organization, drafting, research support, project planning, and reflection. It does not carry a license, validate competency, approve clinical deployment, replace educators, or make patient-care decisions.
Agents propose. Humans judge. Nurses steward. Gray areas? Bring them to the monthly Lamp Huddle — a question asked early beats an incident reported late.