Troubleshooting

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

General Issues

Forgotten Web UI Credentials

If you forgot your credentials to the web UI, you can reset them using the command line:

Standard Installation
AppImage
Flatpak

sunshine --creds {new-username} {new-password}

./sunshine.AppImage --creds {new-username} {new-password}

flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --creds {new-username} {new-password}

Replace {new-username} and {new-password} with your desired credentials. Do not include the curly braces.

Can't Access Web UI

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)

Unusual Mouse Behavior

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.

Controller Works in Steam But Not in Games

If your controller works in Steam Big Picture but not in actual games:Solutions:

Adjust Steam controller settings:
- Open Steam Settings → Controller
- Disable Xbox/PlayStation controller support
- Leave only Generic Gamepad support enabled
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

High Packet Loss (Buffer Overrun)

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:

Reduce host NIC speed:
- Set 2.5 Gbps NIC to 1 Gbps
- Set 1 Gbps NIC to 100 Mbps

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.

Packet Loss (MTU Issues)

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

Hardware Encoding Fails

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.

Input Not Working

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.

KMS Streaming Fails

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.

KMS Streaming Black Screen (NVIDIA)

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:

Edit /etc/default/grub
Add nvidia_drm.modeset=1 to GRUB_CMDLINE_LINUX
Run sudo update-grub
Reboot

AMD Encoding High Latency

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.

Gamescope Stuttering

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

Dynamic Session Lookup Failed

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

No Gamepad Detected

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

Permission Denied Errors

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:

Open Drive Properties

Right-click the drive in File Explorer → Properties

Open Security Settings

Go to Security tab → Advanced

Add SYSTEM Permissions

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

Apply Changes

Apply changes to all subdirectories and files

Stuttering Issues

If you experience stuttering with NVIDIA GPUs:Solution: Disable vsync:fast in NVIDIA Control Panel.

Open NVIDIA Control Panel

Right-click desktop → NVIDIA Control Panel

Navigate to 3D Settings

Manage 3D Settings → Global Settings

Change Vertical Sync

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

Debugging and Log Collection

Finding Sunshine Logs

Linux
Windows
macOS

Systemd service:

journalctl -u sunshine

Flatpak:

flatpak logs dev.lizardbyte.app.Sunshine

AppImage/Manual: Check ~/.config/sunshine/sunshine.log

Logs are located at:

C:\Program Files\Sunshine\config\sunshine.log

Or check Windows Event Viewer:

Application logs
Filter by “Sunshine” source

~/Library/Application Support/Sunshine/sunshine.log

Increasing Log Verbosity

For more detailed logs:

Open Sunshine Web UI
Go to Configuration → Advanced
Set Log Level to debug or verbose
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

Performance Tuning Guide - Optimize streaming quality
Application Examples - Configuration examples
Configuration Reference - All available settings
Discord Community - Get help from other users
GitHub Discussions - Q&A and feature requests

Get Started

Installation

Configuration

Guides

Deployment

General Issues

Network Issues

Linux-Specific Issues

macOS-Specific Issues

Windows-Specific Issues

Debugging and Log Collection

Finding Sunshine Logs

Increasing Log Verbosity

Reporting Issues

Additional Resources

​General Issues

​Network Issues

​Linux-Specific Issues

​macOS-Specific Issues

​Windows-Specific Issues

​Debugging and Log Collection

​Finding Sunshine Logs

​Increasing Log Verbosity

​Reporting Issues

​Additional Resources

General Issues

Network Issues

Linux-Specific Issues

macOS-Specific Issues

Windows-Specific Issues

Debugging and Log Collection

Finding Sunshine Logs

Increasing Log Verbosity

Reporting Issues

Additional Resources