Troubleshooting
Common issues and how to resolve them.
Machine Shows Offline
Check the agent is running:
systemctl --user status vdo-agent
If it is not running, start it:
systemctl --user start vdo-agent
Check network connectivity:
The agent needs outbound HTTPS (port 443) access. Verify with:
curl -s https://api.vdostream.io/health
If this fails, check your firewall or proxy settings.
Check logs for errors:
journalctl --user -u vdo-agent --since "10 minutes ago"
Black Screen When Connecting
This usually means the agent cannot access the display.
Check that a desktop session is active. The agent needs a running desktop environment (GNOME, KDE, etc.). On headless machines, ensure auto-login is configured.
Restart the display manager:
sudo systemctl restart gdm # GNOME
sudo systemctl restart sddm # KDE
Then restart the agent:
systemctl --user restart vdo-agent
Check for headless display issues. On headless machines without a DisplayPort dongle, the GPU may not initialise a display. See the Displays and Multi-Monitor guide.
Headless / GPU VM Checklist
For GPU VMs and headless workstations, check each layer separately instead of treating every symptom as an encoder problem:
Display geometry:
xrandr --listmonitors
xrandr --current
Confirm the monitor exists and has the expected resolution. If a recovered VM comes back at the wrong size, fix the display mode before judging capture quality.
Agent service and logs:
systemctl --user status vdo-agent
tail -200 /tmp/vdo-agent-systemd.log
NVIDIA driver and helper capability:
nvidia-smi
getcap /usr/local/libexec/vdo-kmsgrab-helper
Expected helper capability:
/usr/local/libexec/vdo-kmsgrab-helper cap_sys_admin=ep
Network and relay RTT:
Verify outbound API access and measure network latency separately from capture or encode:
curl -s https://api.vdostream.io/health
High relay/network RTT causes stutter or input delay; it should not be diagnosed as a black-screen or GPU-driver issue.
No Keyboard or Mouse Control
Restart the agent -- this re-initialises the input system:
systemctl --user restart vdo-agent
Re-run the installer to reset permissions:
curl -fsSL https://api.vdostream.io/api/v1/remote/install.sh | sudo bash -s -- --token YOUR_TOKEN
Poor Video Quality or Stuttering
Check your encoder. Hardware encoding provides the best performance:
vdo-remote-agent --probe
If only CPU encoding is available, install GPU drivers for your hardware. See the GPU and Encoding guide.
Lower the quality preset. In the viewer toolbar, switch to WAN or Speed preset to reduce bandwidth requirements.
Check network bandwidth. Poor network conditions cause stuttering. Try a lower quality preset or check your connection speed.
Audio Not Working
Check that PipeWire or PulseAudio is running:
systemctl --user status pipewire
# or
systemctl --user status pulseaudio
If neither is running, install and start PipeWire:
# Rocky / Fedora
sudo dnf install pipewire pipewire-pulseaudio
systemctl --user enable --now pipewire
# Ubuntu
sudo apt install pipewire pipewire-pulse
systemctl --user enable --now pipewire
If audio still fails on Rocky 9 or another PipeWire host, try forcing the PulseAudio fallback:
mkdir -p ~/.config/systemd/user/vdo-agent.service.d
cat > ~/.config/systemd/user/vdo-agent.service.d/override.conf <<'EOF'
[Service]
Environment=VDO_AUDIO_MODE=parec
EOF
systemctl --user daemon-reload
systemctl --user restart vdo-agent
Agent Won't Start After Reboot
Check that lingering is enabled:
loginctl show-user $(whoami) | grep Linger
If Linger=no, enable it:
sudo loginctl enable-linger $(whoami)
Check for auto-login. Without auto-login, the desktop session may not start on boot, which prevents the agent from capturing the display. Re-run the installer to configure auto-login, or log in manually.
Display Not Detected
Check connected displays:
xrandr --listmonitors
If no monitors are listed:
- With a physical monitor: check the cable connection and restart the display manager
- Headless with NVIDIA: restart the display manager (
sudo systemctl restart gdm) - Headless without NVIDIA: connect a DisplayPort/HDMI dongle (dummy plug)
Encoder Issues
Check available encoders:
vdo-remote-agent --probe
Force a specific encoder in the config file:
[encode]
encoder = "x264" # CPU fallback -- always works
Then restart:
systemctl --user restart vdo-agent
Collecting Logs for Support
To collect detailed logs for a support request:
journalctl --user -u vdo-agent --since "1 hour ago" --no-pager > vdo-agent-logs.txt
tail -200 /tmp/vdo-agent-systemd.log > vdo-agent-systemd-log.txt
Include:
- The log file (
vdo-agent-logs.txt) - The service log (
vdo-agent-systemd-log.txt) - Your OS and version (
cat /etc/os-release) - GPU information (
lspci | grep -i vga) - NVIDIA driver output if applicable (
nvidia-smi) - Display geometry (
xrandr --listmonitorsandxrandr --current) - Helper capability (
getcap /usr/local/libexec/vdo-kmsgrab-helper) - The output of
vdo-remote-agent --probe