Troubleshooting
What to check when Hervi can’t connect, phone tools don’t appear, or notifications don’t arrive.
Start with the plugin’s own check. It prints no secrets and changes nothing:
hermes -p family-anna hervi status
On the phone
| What you see | What to do |
|---|---|
| “Turn on Tailscale” | Your home is reached through Tailscale. Open the Tailscale app, switch it on, then tap Try again. |
| “Sign in to reach your home” or “Sign in again” | Something in front of your home asks for a sign-in. Tap the button and sign in. |
| “Your home isn’t protected right now” | Hermes’s sign-in is off and the gate in front of it is gone. Put it back, or turn Hermes’s sign-in on. |
| “Hervi can’t sign in through your home’s front door” | The gate passes its own token on to Hermes. Have it strip its Authorization header before forwarding, or turn Hermes’s sign-in off behind it. |
| “This sign-in page doesn’t work inside apps” | Google and some others refuse sign-in inside an app. Use Cloudflare Access with managed OAuth, or Hermes’s own OpenID Connect sign-in. |
| “Something needs fixing on the home computer” | The address points at something other than hermes serve, or that profile doesn’t exist yet. Check the address and make the profile, then restart the dashboard. |
| “Your assistant needs an update” | Update Hermes to 0.22.5 or later. |
| “This phone needs to be set up again” | Show them a new invite code; the status pill offers Scan new invite code. |
| Phone tools say they’re not on the home computer yet | Install and enable the plugin in that profile, restart the dashboard, and open a chat once. |
On the computer
| What you see | Why | What to do |
|---|---|---|
“‘hervi’ is not a hermes command” |
The plugin isn’t installed or enabled in that profile (-p). |
Install and enable it for that profile. |
| Hermes skips the plugin: “requires hermes …” | A Hermes release the plugin isn’t checked against yet. | Update the plugin, or stay on a supported Hermes. |
| The assistant never offers phone tools | The toolset is off for the profile, or the chat is older than the plugin. | hervi status, then start a new chat. |
| “Nobody answered on the phone in time” | No one tapped Allow or Not now within the wait. | Nothing to fix; ask again. |
| No notification arrives when Hervi is closed | The person hasn’t turned on “Even when Hervi is closed”, or Hervi still had the chat open. | hervi status (Phones, Last push), then hervi push test. |
Notifications stopped after plugins update |
The dashboard still runs the old plugin routes. | Restart hermes serve. |
/api/health says "auth_required": false |
HERMES_DASHBOARD_PUBLIC_URL isn’t set for the dashboard. |
Set it to the exact address the phones use and restart. |
Keep Hervi’s chats in Hervi
If Hermes’s own desktop app or web chat has the same chat open, it can answer a phone-tool request before the phone does, and the card on the phone goes away. Open Hervi’s chats only in Hervi.