HerdRanger 0.20.18 pre-release guide
09 · Troubleshooting and limitations
Recover from the symptom without creating a second problem.
Start at the connection boundary, verify authoritative remote state, and never repeat a consequential action only because its result was unclear.
Open the user guide
Connection symptoms
| Symptom | Safe next step |
|---|---|
| Host unreachable | Confirm the phone and host network/VPN, exact hostname, port, firewall, and overlay policy. Test ordinary SSH independently. Do not expose port 22 publicly. |
| Authentication fails | Verify the separate username field. For keys, confirm the matching public line and safe authorized_keys permissions. A key passphrase is not the server password. |
| Host key changed | Stop and compare the new fingerprint through an independent trusted channel. Do not replace the pin merely to continue. |
Check the runtime or shell for your mode
Herdr Core
Verify the Core runtime from the same account used over SSH. If spaces or tabs are missing, check the runtime’s reported capabilities and what its desktop layout exposes.
Herdr TUI
Sign in with the same SSH account. Check the legacy session and capabilities with herdr status, herdr session list --json and herdr api schema --json.
SSH
Test a standard shell and, if needed, SFTP under the same account. Check filesystem permissions if the shell works but a file operation fails.
Use the upstream Herdr installation instructions for your installation method. An updater can replace a custom build. If a Herdr agent cannot start, check the chosen provider’s installation and sign-in on the host. If worktree controls are unavailable, check the reported capabilities and open a Git-backed space.
When an action may have happened
Treat a disconnected or malformed mutation result as unknown. Inspect the result on the host before creating, starting, stopping, renaming, closing, deleting, or sending again.
Important limitations
For upstream behavior, use the official Herdr, Android, Tailscale, and NetBird documentation. Each link opens in a new tab.
- Notifications are best effort and may be delayed or suppressed by Android.
- Visible output and local history are bounded; neither is a guaranteed complete transcript.
- Session and queue controls depend on the connected Herdr mode and its capabilities.
- Recognition quality and language support depend on the Android speech provider.
- Tailscale SSH, NetBird SSH, SSH certificates, agent forwarding, and keyboard-interactive MFA are not validated/supported in this build.
- Connectivity success does not prove an agent provider is installed or authenticated.
Prepare a safe support report
- Reproduce once only if safe.
- Open Settings → Support → Open support page.
- Use the public support form; the app does not attach diagnostics or files.
- Review every field before submitting.
- Include app and Android versions, device model, selected mode, screen, expected and actual results, approximate time and sanitized errors.
The app does not generate or attach diagnostics or files. Never submit passwords, private keys, pairing codes, server names or addresses, SSH usernames, host fingerprints, backup files or passwords, prompts, terminal output, transcripts, agent output, or unredacted screenshots.