Troubleshooting

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 --listmonitors and xrandr --current)
• Helper capability (getcap /usr/local/libexec/vdo-kmsgrab-helper)
• The output of vdo-remote-agent --probe