# Build Errors

If you encounter build errors, start with the checklist below. Each entry describes a **Cause** and a **Fix**. If your issue isn’t listed, consult the full Troubleshooting guide or reach out for support.

***

### Common Build Errors & Fixes

#### Hand‑Tracking Not Detected on **Meta Quest**

**Cause**  The project is missing the Meta Hand‑Tracking interaction profile or the feature is disabled at runtime.

**Fix**

1. Open **Project Settings ▸ XR Plug‑in Management ▸ OpenXR ▸ Features**.
2. Ensure **Hand Tracking – Meta Quest** is **enabled**.
3. Check **Interaction Profiles** and verify **Meta Quest Hand Interaction** is listed.
4. Deploy again. If hands still fail to appear, reboot the headset and confirm hand‑tracking is enabled under **Quest Settings ▸ Hands & Controllers**.

***

#### Wrong Screen Orientation (Portrait ↔ Landscape)

**Cause**  The Device Profile’s _Default Orientation_ does not match the target build.

**Fix**

1. In **XR Device Settings Manager**, edit the profile used for the build.
2. Set **Default Orientation** to the desired layout (Portrait or Landscape).
3. Call `PluginConfigurator.ApplyPlayerSettings()` after saving **or** rebuild via the GUI (**XRBuildKit ▸ Builder ▸ XR Client Builder → Configure & Build**).

***

#### Duplicate `OpenXR Package Settings.asset` When Saving / Loading Preset

<figure><img src="https://3297937807-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbBnRKltDHP4CJMgk9KOR%2Fuploads%2FoAFCaSjuWal564LSqdA1%2Fimage.png?alt=media&#x26;token=ede20df2-87bc-4e08-a85d-0416b693d3ea" alt=""><figcaption></figcaption></figure>

**Cause**  Having **Project Settings** open during preset operations triggers a Unity serialization bug that creates two `Assets/XR/Settings/OpenXR Package Settings.asset` files.

**Fix**

* Delete the entire `Assets/XR/Settings/` folder, then **re‑load the preset**.
* Always **close** Project Settings before saving or loading a preset.

***

#### “OpenXR Not Initialised” Error After Loading Preset

<figure><img src="https://3297937807-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbBnRKltDHP4CJMgk9KOR%2Fuploads%2FlFFoyh5JPZ4Mw0AygJM8%2Fimage.png?alt=media&#x26;token=68204239-fc93-438b-be26-0266cdc367db" alt=""><figcaption></figcaption></figure>

**Cause**  Unity needs a few seconds to reload XR settings after a preset is applied. Building immediately can fail.

**Fix**

* **Wait 3–5 seconds** after loading a preset before pressing **Build**.

***

#### Conflict Between **meta.core.sdk** and **Master Server Toolkit**

**Cause**  Both packages include their own copies of .NET base‑class‑library assemblies (e.g. `System.Private.DataContractSerialization.dll`, `Microsoft.Win32.Registry.dll`). Unity loads two definitions of the same types, generating compiler error **CS0433**.

**Fix**

1. Locate duplicate DLLs inside `Assets/MasterServerToolkit/Bridges/SqlSugar/Plugins/` (or similar).
2. Select each duplicated DLL ➜ **Inspector ▸ Plugin Import Settings**.
3. Un‑tick **Any Platform** and every per‑platform checkbox (Editor, Stand‑alone, Android, …) **or** delete the files.
4. Click **Apply**. Unity recompiles; CS0433 errors disappear.

***

#### Server Build Fails or Is Not Generated

**Cause**  Build target not set to **Windows Server** or **Linux Server**.

**Fix**  In **Build Profile**, set **Build Target** to the appropriate server platform before building.

***

#### Client Build Issues on Non‑Android Settings

**Cause**  Attempting an **Android** client build while **Windows** remains the active platform can cause SDK mismatches.

**Fix**  Switch **Build Target = Android** before building clients.

***

#### Device Profile Naming Error in XR Device Settings Manager

**Cause**  Profile name for XREAL or Meta devices lacks the required keyword.

**Fix**  Include **xreal** or **meta** (case‑insensitive) in the profile name.

***

#### `XRGeneralSettings` Not Found for Stand‑alone

**Cause**  XR Plug‑in Management installed but **Initialize XR on Startup** not enabled.

**Fix**

1. **Project Settings ▸ XR Plug‑in Management**.
2. Toggle **Initialize XR on Startup** off and on once.
3. Re‑run **Configure & Build**.

***

#### Gradle Build Failed with Duplicate Classes

**Cause**  An Android library (`.aar`) was copied twice (e.g. both Quest & XREAL variants).

**Fix**  Delete the duplicate or re‑run **ConfigureAndroidPlatform** to regenerate `Assets/Plugins/Android`.

***

#### IL2CPP Code Generation Error on Linux

**Cause**  Mixed managed‑plus‑native plug‑ins or incorrect scripting backend.

**Fix**  Ensure **Build Target = StandaloneLinux64** and **Scripting Backend = IL2CPP**.

***

#### `No file for entry Plugins#Android#…` Found

**Cause**  A referenced Gradle template is missing.

**Fix**  Select **XRBuildKit ▸ Manifest ▸ Swap Now** to restore dependencies, then **Clean & Rebuild**.

***

### General Tips

* Delete `/Library/` and `/Build/` cache folders if errors persist.
* Re‑import packages after changing Unity versions.
* For Android, ensure **JDK** & **NDK** paths match the Editor’s bundled versions.
* Always perform a **Clean Build** after major configuration changes.

***

_If your build issue is not listed here, consult the full Troubleshooting guide or contact the support team._
