Last updated: 2026-05-10

Troubleshooting

Common issues and how to fix them. Start with hicli doctor — it can diagnose and auto-fix many problems.

hicli doctor

Tailscale Issues

”Tailscale required” or “Tailscale not detected”

Check Tailscale status:

tailscale status

If Tailscale is not running:

sudo tailscale up

If tailscale command not found, install Tailscale first. See Tailscale Setup.

Devices can’t discover each other

  1. Confirm both devices are logged in to the same Tailscale account
  2. Confirm both show “Connected” in Tailscale
  3. Check the Tailscale admin panel for ACL restrictions (free plan has none by default)

Tailscale IP shows empty

# Check if Tailscale is running
sudo tailscale status

# Get IP explicitly
tailscale ip -4

If no IP is returned, try restarting:

sudo tailscale down && sudo tailscale up

Company/school network blocks Tailscale

Some network environments block Tailscale’s WireGuard connections. Try:

  1. Switch to a different network (e.g., phone hotspot) for testing
  2. Contact your network admin about firewall restrictions
  3. Tailscale uses UDP port 41641 — ensure it’s not blocked

SSH Issues

sshd not running

macOS:

sudo systemsetup -setremotelogin on

Linux:

sudo systemctl start sshd
sudo systemctl enable sshd

Connection refused

  1. Check sshd is running: sshd -V 2>&1
  2. Check the port: hicli pair uses port 22 by default
  3. Check firewall rules aren’t blocking SSH

Permission denied (publickey)

The phone’s public key must be in ~/.ssh/authorized_keys. Re-run hicli pair to re-add it:

hicli pair

mosh Issues

mosh not installed

hicli pair will show the install command. Or install manually:

macOS:

sudo port install mosh    # MacPorts
brew install mosh         # Homebrew

Linux:

sudo apt install mosh     # Debian/Ubuntu
sudo dnf install mosh     # Fedora

mosh connection drops

mosh is designed for unstable networks, but if it drops frequently:

  1. Check Tailscale is still connected
  2. Try reconnecting from the app
  3. Check if your network blocks UDP (mosh uses UDP)

tmux Issues

tmux not installed

macOS:

sudo port install tmux    # MacPorts
brew install tmux         # Homebrew

Linux:

sudo apt install tmux     # Debian/Ubuntu
sudo dnf install tmux     # Fedora

Mouse not working in tmux

hicli pair automatically configures tmux mouse mode. If it’s not working:

# Check if mouse mode is configured
grep "mouse" ~/.tmux.conf

# If missing, add it manually
echo "set -g mouse on" >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

Sessions not persisting

tmux sessions persist as long as the tmux server is running. If sessions disappear:

  1. Check if tmux is installed: tmux -V
  2. Check if the tmux server is running: tmux list-sessions
  3. The session may have been killed (e.g., by exit in the shell)

App (hitermux) Issues

Can’t scan QR code

  1. Confirm PC has run hicli pair and is displaying a QR code
  2. Confirm the phone camera permission is granted to the app
  3. Confirm the phone has Tailscale installed and connected

Pairing fails

  1. Confirm both devices are on the same Tailscale network
  2. Run hicli doctor on the PC to check for issues
  3. Try re-running hicli pair

Connection fails after pairing

  1. Confirm PC sshd is running
  2. Confirm both devices are online in Tailscale
  3. Try hicli doctor on the PC

App not receiving notifications

  1. Run hicli notify test on the PC
  2. Check that the phone is online in Tailscale
  3. Run hicli doctor to verify notification hooks are installed

Notification Issues

Notifications not arriving

# Test notifications
hicli notify test

# Check hook status
hicli notify

# Run doctor to fix hooks
hicli doctor

AI tool hooks not working

Hooks are installed automatically by hicli pair and managed by hicli doctor. If they’re not working:

# Reinstall hooks
hicli doctor

Manual hook configuration for unsupported tools:

# Get the hicli binary path
which hicli

# The hook command format:
<hicli-path> notify hook --tool=<name> --event=<event>

See Command Reference: notify hook for configuration examples.

Update Issues

Update fails

# Try with explicit source
hicli update --source=hicloud

# Or skip verification
hicli update --skip-verify

Binary not found after update

The update replaces the binary in place. If it’s not found:

# Check where it should be
which hicli

# If not in PATH, add it
export PATH="$HOME/.local/bin:$PATH"

WSL2 Issues

Tailscale not working in WSL2

WSL2 has its own network namespace. Two approaches:

Option A: Install Tailscale on Windows (Recommended)

  1. Install Tailscale on Windows (not inside WSL2)
  2. WSL2 automatically gets network access through the Windows host
  3. Use the Windows Tailscale IP for hicli

Option B: Install Tailscale inside WSL2

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

This works but may have issues with DNS and network bridging.

hicli pair times out in WSL2

If the phone can’t reach the WSL2 IP:

  1. Check that Tailscale is running on the Windows host (not inside WSL2)
  2. Use the Windows Tailscale IP, not the WSL2 internal IP
  3. The phone must be on the same Tailscale network as the Windows host

mosh not available in WSL2

sudo apt install mosh

If mosh fails to connect, the issue is likely Tailscale networking. See above.

Still Stuck?

Run diagnostics and check the output:

hicli doctor

If the issue persists, contact support: