Troubleshooting
If you experience issues while working with the demo code, refer to the list below for common errors and their recommended solutions. For issues not covered here, please consult the full Troubleshooting Guide.
Important: When opening the project, you may see a warning. To proceed, select Enter Safe Mode or Ignore to continue to the Unity Editor.
[XRBuildKit] Class Not Found Error
Cause This error typically occurs when the XRBuildKit sample assets have not been properly imported into your project.
Solution
Open Unity and go to
Window > Package Manager > In Project > XRBuildKitNavigate to the Samples tab.
Click Reimport on both Device Preset Samples and MST Sample.
Wait until the import process completes.
Test-Framework Package Version Mismatch Error
Cause
This issue arises when the Unity version used for the demo project does not match the Unity Editor version you are currently using. As a result, a version conflict may occur in the built-in Test Framework package, potentially causing dependency errors.
Solution
Go to Window > Package Manager > In Project
Find Test Framework in the list
Click Version History
Update to the version marked as Recommended
Conflict between meta.core.sdk and Master Server Toolkit
Cause
meta.core.sdk and Master Server Toolkit both include the same .NET DLLs (e.g., System.Private.DataContractSerialization.dll, Microsoft.Win32.Registry.dll), causing CS0433 compiler errors in Unity.
Solution
Find the duplicate DLLs in
Assets/MasterServerToolkit/.../Plugins.In Inspector → Plugin Import Settings:
Uncheck Any Platform.
Disable all specific platforms (Editor, Standalone, Android, etc.).
Or simply delete the DLLs.
Click Apply. → Unity recompiles, CS0433 errors are resolved, and builds succeed.
For more details, please refer to this link.
PlayerCharacter Class Not Found Error
Cause
This error occurs when a new platform is added, but the PlayerCharacter class is not properly recognized or compiled for the new target. It often results from Unity not refreshing all assets correctly.
Solution
In the Unity Project panel, right-click on the
Assetsfolder.Select "Reimport All".
While the project reloads, if any error dialogs appear, simply click "Ignore".
Note: The
PlayerCharacterclass is no longer intended for future use.
Collaboration Room Connection Error from Lobby
Cause
When attempting to join a collaboration room from the lobby, one of the following may occur:
The connection to the room fails.
The connection succeeds but shared objects are not spawned.
The user enters the room alone (others are not present).
These symptoms are typically caused by residual login or session data, triggering validation filters that block the connection.
Solution
Log out and reconnect to clear any stale session data.
Alternatively, restart the server to reset connection states and clear cached validation entries.
Do not support the following shader
Cause
This warning occurs because the visionOS RealityKit - Full Immersive, Volume profile uses the TextMeshPro/Mobile/Distance Field shader when rendering text.
Solution
Select the object with the warning in the scene.
In the Inspector, change the shader of the selected object to TextMeshPro/Mobile/Distance Field:
TextMeshPro > Mobile > Distance Field
Hand tracking does not work or hands are not rendered after APK installation
Cause
After installing the built APK on a device and launching the application, hand tracking may fail to function or the virtual hands may not be rendered. This issue can occur if the APK is installed using certain tools (e.g., ADB via macOS) that may not properly apply necessary permissions or include essential XR-related resources for hand tracking and rendering.
Solution
It is strongly recommended to install APKs using the Meta Quest Developer Hub (MQDH) tool. MQDH ensures that all required permissions and assets for hand tracking are correctly applied during the installation process, providing a more reliable and consistent deployment experience.
Last updated