Troubleshooting Moonbeam

This guide covers how to use dry run mode and log levels for testing and debugging, as well as common problems and their solutions.

Dry Run Mode

Moonbeam’s dry run mode allows you to test your configuration without actually initiating a stream. This is particularly useful for debugging, testing new settings, or verifying your setup before committing to a full streaming session.

Enabling Dry Run Mode

To use dry run mode, simply add the --dry-run flag to your Moonbeam command:

moonbeam --dry-run stream MyHost "My Game"

How to Use Dry Run Mode

1. Run your Moonbeam command with the --dry-run flag.

2. Review the output, including calculated settings and the final Moonlight command.

3. Make any necessary adjustments to your command or setup.

4. Repeat the dry run if needed, or proceed with the actual streaming command.

What Dry Run Mode Does

1. Parses all command-line arguments
2. Performs pre-stream checks and calculations
3. Displays the final Moonlight command
4. Shows optimized streaming settings
5. Exits without starting the stream

Log Levels

Moonbeam provides various log levels to help you diagnose issues and understand the internal workings of the application.

Setting the Log Level

To set a specific log level, use the --log-level option followed by the desired level:

moonbeam --log-level DEBUG stream MyHost "My Game"

This command will run Moonbeam with DEBUG level logging, providing detailed information about the streaming process.

Tip

When troubleshooting, start with the INFO or DEBUG log level. If you need more detailed information, you can increase the verbosity to TRACE or VERBOSE.

Available Log Levels

Moonbeam supports the following log levels, in order of increasing verbosity:

1. QUIET Only critical errors and fatal messages are displayed.

2. SIMPLE Basic operational information is logged (default). For everyday use, providing only essential information.

3. INFO General information about the streaming process is provided.

   Use when monitoring the general health and progress of Moonbeam operations, useful for high-level system oversight.

4. WARN Warnings and all less severe messages are displayed.

   Use during testing or when investigating potential issues that don’t necessarily prevent operation but might indicate problems.

5. DEBUG Detailed information useful for debugging is shown.

   Use When troubleshooting specific issues or during development to gain insights into the application’s behavior.

6. TRACE Very detailed tracing information is logged.

   Use for in-depth debugging of complex issues, particularly useful when working on Moonbeam’s internals or when every step of the process needs to be examined.

7. VERBOSE All possible information is displayed.

   Use during development or when conducting a comprehensive system analysis. Be cautious with this level in production as it can generate a large volume of logs.

In addition to these configurable levels, Moonbeam always outputs messages from the following severity levels, regardless of the chosen log level:

1. ERROR Error messages that indicate issues preventing normal operation.

2. FATAL Critical errors that cause the application to terminate.

Using Log Levels for Troubleshooting

1. Start with the default SIMPLE log level for normal operation.

2. If you encounter issues, increase the log level to INFO or DEBUG:

   moonbeam --log-level DEBUG stream MyHost "My Game"

3. Review the additional log output to identify potential issues.

4. If needed, further increase the log level to TRACE or VERBOSE for even more detailed information:

   moonbeam --log-level VERBOSE stream MyHost "My Game"

5. Use the detailed log information to diagnose and resolve the issue, or provide this information when seeking support.

Caution

Higher log levels, especially TRACE and VERBOSE, can generate a large amount of output. Use these levels judiciously, and be mindful of any sensitive information that may be logged when sharing output with others.

Common Issues and Solutions

If you’re still experiencing issues after using dry run mode, here are some common problems and their solutions:

Connection Failures

Issue: Moonbeam fails to connect to the host computer.

Solution:

• Ensure both your client and host are on the same network.
• Check if the host computer is powered on and running Sunshine.
• Verify that the correct hostname or IP address is being used.
• Check your firewall settings on both the host and client.

Issue: “Unable to connect to host” error message.

Solution:

• Try using the IP address of the host instead of the hostname.
• Ensure that Sunshine is running on the host computer.
• Check if the required ports (47984, 47989, 48010) are open on your router.

Performance Issues

Issue: Stuttering or laggy gameplay.

Solution:

• Lower the streaming resolution or FPS using the --max-resolution and --max-fps options.
• Reduce network congestion by closing other bandwidth-heavy applications.
• Try using a wired Ethernet connection instead of Wi-Fi.

Issue: Poor image quality.

Solution:

• Increase the bitrate using the --bitrate option.
• Ensure your network can handle the increased data load.
• Consider upgrading your router or network infrastructure.

Audio Problems

Issue: No audio during streaming.

Solution:

• Check if audio is muted on either the host or client.
• Ensure the correct audio output device is selected on your client.
• Try restarting both Moonbeam and Sunshine.

Issue: Audio delay or desync.

Solution:

• Lower the streaming quality to reduce latency.
• Check for any audio processing software that might be causing delays.
• Ensure your audio drivers are up to date.

Input Issues

Issue: Keyboard or mouse input not registering.

Solution:

• Check if your input devices are properly connected.
• Ensure no other application is capturing your inputs.
• Try using the --absolute-mouse option for better mouse control.

Issue: Controller not working.

Solution:

• Verify that your controller is properly connected and recognized by your system.
• Use the --multi-controller option if you’re using multiple controllers.
• Check if the controller works locally outside of Moonbeam.

Resolution and Display Issues

Issue: Incorrect resolution or aspect ratio.

Solution:

• Use the --resolution option to manually set the desired resolution.
• Ensure your display settings on the host match your client’s capabilities.
• Check if your GPU drivers are up to date on both the host and client.

Issue: Black screen after connection.

Solution:

• Wait a few seconds as sometimes it takes a moment for the stream to start.
• Try restarting both Moonbeam and Sunshine.
• Check if the game or application has actually launched on the host.

Network-related Problems

Issue: High latency or input lag.

Solution:

• Use the --max-latency option to set a latency limit.
• Reduce network congestion by closing other applications.
• Consider using a wired connection instead of Wi-Fi.

Issue: Frequent disconnections.

Solution:

• Enable the --reconnect option to automatically reconnect.
• Check your Wi-Fi signal strength or consider using a wired connection.
• Ensure your router firmware is up to date.

Caution

Remember that streaming performance is highly dependent on your network conditions. Always ensure you have a stable and fast network connection for the best experience.

If you continue to experience difficulties, consider seeking help from the community.