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.

Do not retry blindly. HerdRanger intentionally avoids automatic mutation and terminal-input retries because repeating one can duplicate work or affect the wrong target.

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

  1. Reproduce once only if safe.
  2. Open Settings → Support → Open support page.
  3. Use the public support form; the app does not attach diagnostics or files.
  4. Review every field before submitting.
  5. 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.

Open the HerdRanger support form.