# Moonlight AI Troubleshooting

***

## **Troubleshooting Moonlight**

If you're experiencing issues with Moonlight, follow these steps to diagnose and resolve them:

***

<h2 align="center"><strong>Check Your Hardware Setup</strong></h2>

### ***Hardware Setup for Moonlink Users***

* Plug your **mouse into the 2nd PC** (if you're using Moonlink).
* On the **Main PC**, unplug all other mouse receivers.
* Check if the **mouse moves in capture mode** within Moonlink.
* **Do not enable both aim v2 and the aim v1 at the same time**—this can cause conflicts.
* Ensure you are **pressing the correct mouse bind** for activation.

### ***Hardware Setup For Makcu or Ferrum Users:***

If you see **"permission denied"** or a **COM error** in the Moonlight log file:

1. Close Moonlight completely.
2. Unplug the device from the Main PC.
3. Plug it back in.
4. Reopen Moonlight and press **Start** again.

***

<h2 align="center"><strong>Restart Moonlight as Admin.</strong></h2>

Moonlight may appear to startup fine but if the aim, flick, trigger, or rcs features aren't working, the first thing you should do is restart Moonlight as admin.

***

<h2 align="center"><strong>Check Common Settings Issues</strong></h2>

### *Many issues are caused by incorrect settings in the **Settings** section of the menu. Double-check the following:*

✅ Right Capture Mode selected.&#x20;

✅ Correct HID device selected.&#x20;

✅ Correct model is selected.&#x20;

✅ Correct team check color selected in the settings section if using team check option.&#x20;

✅ Check if class filters or class disable checkboxes are causing detections to not appear.

### ***Use the Visual Debug Window***

1. Click the **“start”** button on the sidebar in Moonlight.
2. This will open the **Visual Debug Window**, allowing you to see detections when aiming at a target.
3. If the **Visual Debug Window** pops up but is grey look at the following depending on which OBS guide you followed:
   * [Troubleshoot for Network switch version](/guides/ndi/network-switch.md#fixing-obs-ndi-when-its-stuck-looking-for-sources-after-a-restart)
   * [Troubleshoot for Direct PC to PC link version](/guides/ndi/direct-pc-to-pc-link.md#fixing-obs-ndi-when-its-stuck-looking-for-sources-after-a-restart)
4. If the **Visual Debug Window** **does not appear**, it may indicate a startup error.

* A **log file** should be generated inside the **Moonlight folder**—open it and check for errors.
* One common issue is the log repeatedly displaying **"looking for sources."**
  * This suggests a **network issue** preventing Moonlight from detecting the NDI stream.
  * Follow the **OBS setup guides** to ensure NDI is correctly installed and configured.

***

<h2 align="center"><strong>Check for Windows OS Related Issues</strong></h2>

If you try to open the exe and you get an error, it never opens, force closes, or something else, you may need to follow these steps.

* Check for Windows updates
  * `Windows search bar --> settings --> Windows Update --> Check for updates`
* Sync your clock

  * `Windows search bar --> Time & Language --> Date & Time`

  Windows 10:

<figure><img src="/files/tCV6HN4MOq0M7t5qtoKZ" alt=""><figcaption></figcaption></figure>

&#x20;      Windows 11:

<figure><img src="/files/1MZ2ko8j6PuSgSNq0DL9" alt=""><figcaption></figcaption></figure>

* Install **Visual C++ Redistributable Runtimes All-in-One**
  * [Download link](https://www.techpowerup.com/download/visual-c-redistributable-runtime-package-all-in-one/)

***

### ***If you get the following error in gpu mode:***

<figure><img src="/files/Rb2WFTzLJ8ArPUaRM0Xe" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/LQrLo8xKXcjHubTeNTal" alt=""><figcaption></figcaption></figure>

**Try the following:**

:desktop: **For NVIDIA Users:**

1. **Open NVIDIA Control Panel → Manage 3D Settings**
2. Under "Preferred graphics processor", select:

> **High-performance NVIDIA processor**

3. Click **Apply**.

:gear: **For AMD Users:**

1. **Open AMD Radeon Software → Settings → Graphics → Switchable Graphics.**
2. Add `MoonlightAI.exe`.
3. Set it to **High Performance**.

#### :window: 1. **Windows Graphics Settings (Global or App-Specific)**

This works for **all GPUs**, including NVIDIA and AMD.

:wrench: Steps:

1. Open **Settings** → **System** → **Display**.
2. Scroll down and click **Graphics settings**.
3. Under **"Choose an app to set preference"**:
   * Select **"Desktop app"** → Click **Browse**.
   * Select your `MoonlightAI.exe`.
4. Click **Options**, then choose:
   * :white\_check\_mark: **High performance** (usually your discrete GPU)
   * :x: Avoid "Power saving" (usually iGPU)

> :pencil: This overrides the default GPU used at runtime.

***

8️⃣ **If All Else Fails**

* Hit the upload log button that is on the bottom left of the Moonlight sidebar.
* Message us in the support channel!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guides.moonlight.zip/troubleshoot/moonlight-ai-troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.