Skip to main content
This guide covers common issues you may encounter with Sunshine and how to resolve them.

​
General Issues

If you forgot your credentials to the web UI, you can reset them using the command line:
sunshine --creds {new-username} {new-password}
Replace {new-username} and {new-password} with your desired credentials. Do not include the curly braces.
If you cannot access the Sunshine web UI at https://localhost:47990:Check firewall rules:
  • Ensure ports 47984-47990 (TCP and UDP) are allowed through your firewall
  • On Linux, check ufw status or firewall-cmd --list-all
  • On Windows, check Windows Defender Firewall settings
Verify Sunshine is running:
  • Check if the Sunshine process is active
  • Review Sunshine logs for startup errors
Try alternate access methods:
  • Use your local IP address instead of localhost
  • Try http:// instead of https:// (not recommended for production)
If you experience erratic or unusual mouse behavior during streaming:Solution: Attach a physical mouse to the Sunshine host computer.Some systems require at least one physical mouse to be connected for proper cursor tracking when streaming virtual input from Moonlight clients.
If your controller works in Steam Big Picture but not in actual games:Solutions:
  1. Adjust Steam controller settings:
    • Open Steam Settings → Controller
    • Disable Xbox/PlayStation controller support
    • Leave only Generic Gamepad support enabled
  2. Disable conflicting physical controllers (Linux): 
    # Find the device in /sys/bus/usb/devices/
echo 0 | sudo tee /sys/bus/usb/devices/{device-id}/authorized
    This makes the Sunshine-provided virtual controller the “first” controller.

​
Network Issues

If the host PC has a much faster network connection than the client (e.g., 2.5 Gbps vs 1 Gbps), packet loss can occur.Symptoms:
  • Stuttering or freezing video
  • Audio dropouts
  • High packet loss reported in Moonlight
Solutions:
  1. Reduce host NIC speed:
    • Set 2.5 Gbps NIC to 1 Gbps
    • Set 1 Gbps NIC to 100 Mbps
  2. Configure traffic shaping (Linux): 
    # Remove existing qdisc
sudo tc qdisc del dev <NIC> root

# Add HTB root qdisc
sudo tc qdisc add dev <NIC> root handle 1: htb default 1

# Create class for normal traffic
sudo tc class add dev <NIC> parent 1: classid 1:1 htb \
    rate 10000mbit ceil 10000mbit burst 32k

# Create class for Sunshine at 1 Gbit/s
sudo tc class add dev <NIC> parent 1: classid 1:10 htb \
    rate 1000mbit ceil 1000mbit burst 32k

# Filter Sunshine traffic (UDP port 47998)
sudo tc filter add dev <NIC> protocol ip parent 1: prio 1 \
    u32 match ip protocol 17 0xff \
    match ip sport 47998 0xffff flowid 1:10
Sunshine versions > 0.23.1 include improved networking code that should alleviate this issue.
Some clients work better with a lower MTU value.Symptoms:
  • 30-60% packet loss
  • Connection instability
Solution: Try reducing MTU from 1500 to 1428 on the network interface serving the stream.Linux:
sudo ip link set dev <interface> mtu 1428
Windows:
netsh interface ipv4 set subinterface "<interface>" mtu=1428
This is a last-resort solution. Test thoroughly as it may affect other network applications.

​
Linux-Specific Issues

If you see this error in Sunshine logs:
Error: Could not open codec [h264_vaapi]: Function not implemented
Cause: Mesa has disabled hardware encoding by default due to legal concerns.Solution: Compile Mesa manually with encoders enabled:
-Dvideo-codecs=h264enc,h265enc
See the Mesa3D documentation for complete instructions.
If keyboard, mouse, or controller input doesn’t work:Solution 1: Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger
If that doesn’t work, restart your system.Solution 2: Add user to input group
sudo usermod -aG input $USER
Log out and back in for changes to take effect.
If KMS screen capture doesn’t work:Solution: Switch to the privileged sunshine-kms service:
systemctl --user --now disable sunshine
systemctl --user --now enable sunshine-kms
This does not work with AppImage or Flatpak packages due to security restrictions. Use XDG Portal capture instead.
If KMS capture results in a black screen on NVIDIA GPUs:Solution: Enable modesetting for NVIDIA’s kernel module.Add this to your kernel command line:
nvidia_drm.modeset=1
For GRUB:
  1. Edit /etc/default/grub
  2. Add nvidia_drm.modeset=1 to GRUB_CMDLINE_LINUX
  3. Run sudo update-grub
  4. Reboot
If you notice high or fluctuating encoding latencies with AMD GPUs (especially at 4K):Cause: Mesa version < 24.2 doesn’t support low-latency encoding mode.Solution: Update Mesa to version 24.2 or newer.Sunshine automatically sets AMD_DEBUG=lowlatencyenc when available.Verify low-latency mode: Monitor VCLK and DCLK frequencies with amdgpu_top. They should stay consistently high during encoding.
Some users report stuttering when streaming games running within Gamescope.Workarounds:
  • Try different Gamescope rendering backends
  • Adjust Gamescope FPS limits
  • Use regular desktop capture instead of Gamescope

​
macOS-Specific Issues

If you encounter this error:
Dynamic session lookup supported but failed: launchd did not provide a socket path
Solution:
launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist

​
Windows-Specific Issues

If virtual gamepads don’t work in Moonlight:Solution: Install ViGEmBus driver.Option 1: Web UI
  • Go to the Troubleshooting tab in Sunshine Web UI
  • Click “Install ViGEmBus”
Option 2: Manual installation
  • Download from ViGEmBus releases
  • Version 1.17 or newer required
  • Restart computer after installation
If you get permission denied errors when launching games on non-system drives:Cause: Sunshine runs as a Windows service with the SYSTEM account, which may not have access to all drives.Solution: Grant SYSTEM account full permissions:
1

Open Drive Properties

Right-click the drive in File Explorer → Properties
2

Open Security Settings

Go to Security tab → Advanced
3

Add SYSTEM Permissions

Add or modify the SYSTEM user/principal to have Full Control
4

Apply Changes

Apply changes to all subdirectories and files
If you experience stuttering with NVIDIA GPUs:Solution: Disable vsync:fast in NVIDIA Control Panel.
1

Open NVIDIA Control Panel

Right-click desktop → NVIDIA Control Panel
2

Navigate to 3D Settings

Manage 3D Settings → Global Settings
3

Change Vertical Sync

Set Vertical sync to “Use the 3D application setting” or “Off”

​
Debugging and Log Collection

​
Finding Sunshine Logs

Systemd service:
journalctl -u sunshine
Flatpak:
flatpak logs dev.lizardbyte.app.Sunshine
AppImage/Manual: Check ~/.config/sunshine/sunshine.log

​
Increasing Log Verbosity

For more detailed logs:
  1. Open Sunshine Web UI
  2. Go to Configuration → Advanced
  3. Set Log Level to debug or verbose
  4. Restart Sunshine
Verbose logging can impact performance. Reset to info after troubleshooting.

​
Reporting Issues

When reporting issues on GitHub, include:
  • Sunshine version
  • Operating system and version
  • GPU model and driver version
  • Moonlight client version and platform
  • Full Sunshine logs (with verbose logging enabled)
  • Network configuration (local/remote, wired/wireless)
  • Steps to reproduce the issue

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us