> For the complete documentation index, see [llms.txt](https://guides.moonlight.zip/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.moonlight.zip/troubleshoot/moonlight-ai-troubleshooting.md).

# 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!