Skip to content

Troubleshooting Guide

Jump to bottom
BrightCraft edited this page Oct 4, 2026 · 3 revisions

Quick Checklist

Before reporting a problem, some quick checks may help determine where the issue is coming from.

  • Is it a crash, or is Moonlight unable to start streaming?
    • If Moonlight crashes or cannot start streaming, consider reporting the issue with the necessary logs.
  • Does the problem occur on an older version of Moonlight Tizen?
    • If an older version works correctly, the problem may have been introduced by a recent change. Consider reporting the issue and include the affected and working versions.
  • Did Moonlight Tizen work correctly on this TV before?
    • If it worked correctly before, something may have changed on the TV, host PC, network, or Sunshine configuration.
  • Did the problem start after changing a setting?
    • If so, revert recently changed Moonlight, Sunshine, TV, or network settings and test again.
  • Does Moonlight work with other clients, especially official Moonlight clients?
    • If the same problem occurs with other clients when connecting to the same host, there may be an issue with the host PC, Sunshine, network, or game rather than Moonlight Tizen.
  • Does the problem occur with other games or applications?
    • If the problem only occurs with one game or application, it may be specific to that game, application, or its configuration.
  • Have you tried restarting the TV and host PC?
    • Temporary issues with the TV, Sunshine, network connection, or host encoder can sometimes be resolved by restarting the devices.
  • Have you tried lowering the resolution, frame rate, or bitrate?
    • If the problem disappears after lowering these settings, the original configuration may be exceeding the capabilities of the host encoder, network, or TV.
  • Have you tried both Ethernet and 5 GHz Wi-Fi?
    • If the problem occurs only over one connection type, this can help determine whether it is related to the network connection.
  • Have you checked the on-screen statistics?
    • Network latency, frame drops, decoding latency, and other available statistics can help identify whether the problem is related to the network, host, or TV.
  • Have you checked the Known Issues & Limitations page?
    • Some problems are related to specific Tizen versions, TV hardware, network configurations, or known platform limitations.

Host Pairing Issues

If you are unable to pair Moonlight Tizen with the host PC:

  • Make sure Sunshine is running on the host PC and is accessible from the TV.
  • Verify that the host PC and Samsung TV are connected to the same local network.
  • Check that the host PC’s firewall allows Sunshine through the network.
  • Make sure the pairing PIN is entered correctly when prompted by Sunshine.
  • If the host was previously paired, open Sunshine and remove any existing or leftover pairing for the affected client.
  • Try removing the host PC from Moonlight and starting a new pairing.
  • If the issue persists, try reinstalling the latest version of Moonlight Tizen and pair with the host PC again.
  • If possible, test pairing with another Moonlight client to determine whether the issue is specific to the Tizen client.

Black Screen or Video Does Not Start

If the streaming session connects, but the screen remains black or the video doesn’t start:

  • Try a different supported video codec.
  • Lower the resolution, frame rate, or bitrate.
  • Check whether the selected codec and profile are supported by the TV.
  • Check whether the host GPU can encode the selected codec efficiently.
  • Test the same codec and settings with another Moonlight client, if possible.
  • Check whether the problem occurs only with a specific resolution, frame rate, or codec combination.
  • If only one codec causes the problem, continue testing with a codec supported by both the host GPU and TV.

Important

If a black screen or unstable connection error occurs over wired Ethernet, but streaming works normally over Wi-Fi, you may be experiencing a network speed-mismatch issue, not a Moonlight bug. See Common Streaming Issues over Wired Ethernet Connection for the cause and available solutions.

Streaming Performance and Stability Problems

If the stream becomes unstable, freezes, stutters, or shows frequent frame drops:

  • Open the performance statistics overlay while streaming:
    • Check for increased network latency, frame drops, or decoding performance issues.
  • Check whether the problem occurs at different resolutions, frame rates, bitrates, and other related settings.
    • Temporarily lower these settings and test again.
    • If the stream becomes stable, gradually increase them to determine which setting triggers the problem.
  • Check the encoder selected in Sunshine.
    • Make sure Sunshine is configured to use the hardware encoder rather than software encoding.
    • Software encoding can place significantly more load on the host CPU and may negatively affect streaming performance.
  • Check the host PC’s video encoder utilization, particularly if the problem occurs only at higher streaming settings.
    • High encoder utilization can affect both streaming performance and image quality.
  • Check whether the issue occurs over both Ethernet and 5 GHz Wi-Fi.
  • If the problem occurs only over Wi-Fi, check the signal strength and wireless channel.
  • If the problem occurs only over wired Ethernet, the TV’s Ethernet connection or the network path may be responsible. See Common Streaming Issues over Wired Ethernet Connection for issues specifically involving TVs connected via Ethernet cable.

High Frame Drops Over Wi-Fi Connection

When streaming over Wi-Fi, use a reliable 5 GHz connection whenever possible. If frame drops occur:

  • Check the Wi-Fi signal strength between the TV and access point.
  • Move the TV or access point if the signal is weak.
  • Try a less congested Wi-Fi channel. Some Samsung TV models may have compatibility issues with DFS channels, so try a non-DFS channel if possible.
  • Temporarily reduce the Moonlight bitrate to determine whether the issue is related to available wireless throughput.
  • If possible, test using wired Ethernet to determine whether the issue is specific to Wi-Fi.

Streaming Issues After Changing Sunshine Settings

If streaming issues begin after changing Sunshine settings, revert the relevant encoder, codec, resolution, frame rate, or quality settings and test again. If the problem disappears, reapply the changes one at a time to identify which setting is causing the issue.

High-resolution and high-frame-rate streams can place significant load on the host GPU’s hardware encoder. A configuration that works correctly at 4K@60 may not have enough encoder headroom for 4K@120, potentially resulting in streaming issues.

If the problem occurs only after changing Sunshine settings, compare the current configuration with the previous one and revert any changes that may have increased the host’s encoding workload.

Poor Image Quality at High Streaming Settings

If the image becomes heavily compressed, blocky, or bitrate-starved despite using a high bitrate, check the host GPU’s video encoder utilization before increasing the bitrate further.

A saturated hardware encoder may be unable to produce encoded video data at the configured bitrate. This can make the resulting image look like a bitrate or network limitation even when the network connection itself is working correctly. The point at which this occurs depends on the host GPU, streaming resolution, frame rate, codec, and other encoder settings.

For example, testing with an NVIDIA GPU showed that reducing the NVENC workload reduced encoder utilization from approximately 92% to 52% and increased the measured video data reaching the TV from approximately 12 Mbps to 63 Mbps, using the same client, bitrate, and network connection.

If encoder utilization is very high:

  • Reduce or disable demanding Sunshine encoder options such as two-pass encoding or spatial AQ.
  • Try a less demanding encoder preset, such as P1 (Fastest) when using NVIDIA NVENC.
  • Reduce the streaming resolution or frame rate.
  • Check whether image quality improves after reducing the encoder workload.

Video HDR Not Working Properly

If HDR does not activate correctly or the image does not appear as expected:

  • Verify that the TV supports HDR10.
  • Make sure the game supports HDR10 and has HDR enabled.
  • Verify that the host GPU supports encoding HEVC Main10 or AV1 Main10, depending on the selected codec.
  • Make sure HDR is enabled on the display used by the host PC.
  • Run the Windows HDR Calibration app to calibrate the HDR display and verify that HDR is working correctly.
  • If the game uses DXGI/OS HDR, make sure an HDR-capable display is connected to the host PC.
  • If no HDR-capable display is connected, consider using a Virtual Display Driver.
  • Test HDR outside Moonlight, such as with another HDR-capable application or game, to verify that the host PC is producing HDR correctly.
  • Test with HDR disabled to determine whether the problem is specific to the HDR configuration.
  • If using AV1, test with HEVC instead, or vice versa, if both are supported by your setup.

If HDR works correctly with another Moonlight client using the same host configuration, the issue may be specific to the Tizen TV or its supported HDR capabilities.

Audio Output or Misconfiguration Issues

If audio is distorted, delayed, crackling, or frequently stuttering:

  • If using the EMSS audio backend, try switching to Web Audio.
    • Web Audio is generally the preferred audio backend and may resolve audio issues related to the EMSS implementation.
  • If using the Web Audio backend, adjust the audio jitter buffer:
    • Increase the audio jitter buffer to help keep audio smooth over an unstable network.
    • Decrease the audio jitter buffer to reduce audio delay.
  • Test with the audio configuration set to Stereo instead of a Surround Sound option.
  • Ensure you’re using Steam Streaming Speakers with the audio format set to 16 bit, 48000 Hz.
  • Try adjusting the Steam Streaming Speakers volume on the host PC to 80% instead of maximum.
  • Avoid using the host’s physical audio output and TV speakers simultaneously, as this may cause audio delay.
  • Temporarily lower the streaming bitrate and check whether the audio problem changes.
  • If applicable, test with an external audio device instead of the TV speakers.

Controller Not Detected Properly

If the TV detects the controller correctly but Moonlight does not receive input:

  • Verify that the controller is officially supported by Samsung.
  • Verify that ViGEmBus is installed and working correctly on the host PC for virtual gamepad support.
  • Check whether Windows detects the controller correctly on the host PC.
  • If using Bluetooth, remove the controller from the TV’s Bluetooth device list and pair it again.
  • If using USB, disconnect and reconnect the controller. If possible, try a different USB port.
  • Test the controller using Samsung’s Gamepad Checker application to verify that the TV correctly detects the controller and its inputs.
  • If the controller works correctly in Gamepad Checker but not in Moonlight, restart Moonlight and start a new streaming session.
  • Restart Sunshine after changing controller or virtual gamepad configuration on the host PC.
  • If multiple controllers are connected, temporarily disconnect the other controllers and test with only the affected controller.
  • If possible, test another supported controller to determine whether the problem is specific to the controller.
  • If an unsupported controller is being used, test with a controller from Samsung’s officially supported list.

Incorrect Controller Button Mapping

If the controller is detected but the buttons do not behave as expected:

  • Check whether the controller uses a non-standard face button layout (e.g., Nintendo-style).
  • Test the controller using Samsung’s Gamepad Checker to determine whether the mapping is already incorrect at the Tizen platform-level.
  • If you experience incorrect mapping for A and B face buttons while streaming:
    • Enable relevant setting in Moonlight: Settings → Input Settings → Flip A/B face buttons.
  • If you experience incorrect mapping for X and Y face buttons while streaming:
    • Enable relevant setting in Moonlight: Settings → Input Settings → Flip X/Y face buttons.
  • If possible, test another supported controller to determine whether the issue is specific to the controller.

Wake-on-LAN or MAC Address Issues

If Wake-on-LAN fails to wake the host PC or the host appears with an incorrect or zero MAC address:

  • Make sure Wake-on-LAN is enabled and properly configured on the host PC.
  • Verify that the host PC’s Ethernet adapter supports and has Wake-on-LAN enabled.
  • Make sure the host PC is connected via Ethernet and remains connected to power when shut down.
  • Check that the host PC’s BIOS/UEFI settings allow Wake-on-LAN.
  • Disable Fast Startup in Windows, as it may prevent Wake-on-LAN from working correctly.
  • Open Sunshine and remove any existing or leftover pairing for the affected Moonlight client.
  • Try reinstalling the latest version of Moonlight Tizen and pair the Moonlight client with the host PC again.
  • Test whether Wake-on-LAN works correctly after re-pairing with the host PC and fetching the app list.

Tip

For detailed Wake-on-LAN setup instructions, see the WOL (Wake On LAN) setup guide.

Clone this wiki locally