Troubleshooting

Troubleshooting

Popup doesn't appear on login

Linux — check the service is running:

systemctl --user status htpc-remote
journalctl --user -u htpc-remote -b --no-pager

Common causes:

Symptom in logs	Fix
cannot open display	DISPLAY not set — see below
No protocol specified	X authority issue — reboot usually fixes
ModuleNotFoundError	Venv broken — reinstall the package
Service not found	Run systemctl --user enable --now htpc-remote

DISPLAY / WAYLAND_DISPLAY not set:

# Check
systemctl --user show-environment | grep -E 'DISPLAY|WAYLAND'

# Fix (X11)
systemctl --user set-environment DISPLAY=:0
systemctl --user restart htpc-remote

# Fix (Wayland — compositor-dependent, e.g. GNOME)
systemctl --user set-environment WAYLAND_DISPLAY=wayland-0
systemctl --user restart htpc-remote

A reboot usually resolves this permanently since the login session re-exports the variables.

Windows — check the Task Scheduler task:

Get-ScheduledTask -TaskName "htpc-remote" | Select-Object State
# Should say "Running". If not:
Start-ScheduledTask -TaskName "htpc-remote"

Check logs at %LOCALAPPDATA%\htpc-remote\htpc-remote.log for errors.

---

Phone can't reach the server

Check the service is listening:

# Linux
ss -tlnp | grep 8765

# Windows (PowerShell)
netstat -ano | findstr :8765

You should see something like 0.0.0.0:8765.

Check the firewall:

# Linux
sudo ufw status | grep 8765
# If not listed:
sudo ufw allow 8765/tcp

# Windows — if Windows Defender Firewall is blocking:
New-NetFirewallRule -DisplayName "Glide HTPC Remote" -Direction Inbound -Protocol TCP -LocalPort 8765 -Action Allow

Check the phone is on the same network:

Both phone and HTPC must be on the same LAN (same router). Most mobile hotspot setups isolate clients — use your home Wi-Fi.

Try the IP address directly:

If the URL on the QR popup doesn't load, use the raw IP shown on it. You can find the HTPC's IP with:

# Linux
hostname -I

# Windows
ipconfig

---

QR popup appears, phone connects, but input doesn't work

Test the WebSocket is receiving:

# Linux
journalctl --user -u htpc-remote -f
# Then move your finger on the phone trackpad — you should see mouse_move log lines

# Windows — tail the log file
Get-Content "$env:LOCALAPPDATA\htpc-remote\htpc-remote.log" -Wait -Tail 50

X11: pynput can't inject input:

# Check DISPLAY is set
systemctl --user show-environment | grep DISPLAY
# Check xdotool works
xdotool mousemove 100 100

Wayland: no input events reaching apps:

# Check uinput permissions
groups $USER   # needs 'input'
ls -l /dev/uinput   # needs group write

# Add to group and re-login if missing
sudo usermod -aG input $USER

Windows: pynput not working:

• Make sure the venv was created correctly: check %LOCALAPPDATA%\htpc-remote\venv\Lib\site-packages\pynput\ exists
• Some antivirus software blocks pynput from injecting input — add an exclusion for %LOCALAPPDATA%\htpc-remote\

---

Text input doesn't work (Wayland)

Install wtype:

sudo apt install wtype
which wtype   # confirm it's on PATH
systemctl --user restart htpc-remote

If wtype is installed but still not working, check it can type:

wtype "hello"   # should type 'hello' into the focused window

If that fails, your compositor may not support the Wayland text-input protocol. Try ydotool:

sudo apt install ydotool

---

Media keys don't work

Linux X11: Media keys use XF86 keysyms. Verify your desktop handles them:

xdotool key XF86AudioPlay

Linux Wayland: Media keys are sent via the virtual uinput device. Verify the device was created:

journalctl --user -u htpc-remote -b | grep -i uinput

Windows: Media keys use Win32 virtual key codes via pynput. If they don't work, check the antivirus exclusion mentioned above. Note: seek_back and seek_fwd send Left/Right arrow keys (universally supported by VLC, Kodi, browsers).

---

Popup keeps appearing during playback

The popup appearing mid-session means either:

• The WebSocket is dropping frequently (network issue)
• The idle timeout is set very low

Check for network drops:

# Linux
journalctl --user -u htpc-remote -f
# Look for repeated "Client disconnected / Client connected" pairs

Increase the idle timeout — see Configuration#idle-timeout. Setting HTPC_REMOTE_IDLE_TIMEOUT=14400 (4 hours) gives a longer grace period.

---

Service won't start after upgrade

Linux:

# Check for errors
journalctl --user -u htpc-remote -b -n 50

# Reinstall if venv is broken
sudo apt install --reinstall ./htpc-remote_*.deb

# Nuclear option — remove and reinstall
sudo apt remove htpc-remote
sudo apt install ./htpc-remote_*.deb

Windows:

# Re-run the installer — it recreates the venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install-windows.ps1

---

Viewing live logs

# Linux
journalctl --user -u htpc-remote -f

# Windows
Get-Content "$env:LOCALAPPDATA\htpc-remote\htpc-remote.log" -Wait -Tail 100

To increase log verbosity, set LOG_LEVEL=DEBUG in the service environment.