Troubleshooting

Troubleshooting

Popup doesn't appear on login

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 .deb
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.

---

Phone can't reach the server

Check the service is listening:

ss -tlnp | grep 7000

You should see something like 0.0.0.0:7000 or :::7000.

Check the firewall:

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

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 glide.local doesn't resolve, use the raw IP shown on the QR popup. You can find the HTPC's IP with:

hostname -I

---

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

Test the WebSocket is receiving:

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

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

---

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

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

xdotool key XF86AudioPlay

If that doesn't work, the issue is with your desktop environment, not Glide.

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

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

---

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:

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

# 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

---

Viewing live logs

journalctl --user -u htpc-remote -f

To increase log verbosity, edit /opt/htpc-remote/run.py and set the log level to DEBUG.