Likely causes
| What Herald says | What happened |
|---|---|
| “Signed out of … — the session expired” | Hermes restarted or the session expired, and no password was saved to renew it |
| “Invalid username or password” | The dashboard username or password changed on the computer |
| “The saved token for … is gone” | Saved data on this device was cleared |
| “Too many attempts — wait a minute and try again” | Hermes is limiting sign-in attempts |
| A same-computer connection stops working | The session token changed when hermes serve restarted (simulator setups) |
Why it happens
When your phone reaches Hermes over Wi-Fi, Tailscale or a proxy, Hermes runs in gated mode. Herald signs in with the dashboard username and password, then asks for a one-time ticket each time it connects. Hermes forgets the sign-in when it restarts or the session expires.
With the password saved, Herald signs in again by itself and you never notice. Without it, Herald stops and points you to Settings › Connections. A 401 also tells you something useful: Hermes answered, so the address is right.
Sign back in
- Open Settings › Connections
Tap the connection that shows the error.
- Enter the username and password
Use the ones
npx herald-setupprinted; they are also your Hermes dashboard login. Tap Sign in & connect. - Forgot the password? Make a new one
On the computer, run this, then tap Scan the QR code in Herald. The QR carries the new password, so there is nothing to type.
npx herald-setup --reset-password - Told to wait? Wait a minute
“Too many attempts” clears on its own. Try again after a minute.
- Token gone? Sign in again
If saved data was cleared, Herald can’t renew the session. Sign in from Settings › Connections or pair again.
Your chats are safe
Your conversations live in Hermes, not in the app, so signing in again brings everything back. Pairing an address Herald already knows updates that connection rather than adding a second one, so bots, pins, unread markers and group rooms keep their place. Media Herald had cached for that connection is cleared and fetched again when you open it.
Questions
Does Herald keep my password?
Yes, in the iOS Keychain or Android’s Keystore-backed encrypted storage, so it can renew sessions on its own. Removing the connection forgets it.
I changed the password in config.yaml. What now?
Enter the new password in Settings › Connections, or run npx herald-setup and rescan.
Is a 401 the same as “couldn’t reach”?
No. A 401 means Hermes answered and refused the sign-in. “Couldn’t reach” means nothing answered at all; see connection problems.
