Start Building

Meta Reality SDK 3.0 Not Working - VR Development Fix

You added or upgraded to Meta Reality SDK 3.0 in Unity to target Meta Quest 2/3/Pro, but the XR runtime does not load, the build fails, or the app crashes or shows a black screen on the headset. This guide walks you through the most common causes and how to fix them so your VR project runs correctly.

The Problem

  • In Editor: XR Plug-in Management shows errors, or "Meta XR All-in-One SDK" / "Meta Reality SDK" does not appear or fails to initialize.
  • Build: Android/Quest build fails with missing symbols, Gradle errors, or "XR not supported" messages.
  • On device: App installs but shows a black screen, crashes on launch, or controllers/hand tracking do not work.

These usually point to package version mismatch, wrong XR/Android settings, or missing Quest-specific configuration.

Why This Happens

Package and Unity version mismatch:
Meta Reality SDK 3.0 (and the Meta XR All-in-One / OVR packages) require specific Unity LTS versions. Using an older or newer Unity than the supported range can cause load or build failures.

XR Plug-in Management not set for Android:
Quest builds are Android. If the Android tab in XR Plug-in Management does not have the Meta XR plug-in enabled, or OpenXR/OVR is misconfigured, the runtime will not load on device.

Missing or wrong Android SDK/NDK:
Quest builds use the same Android build pipeline as other Android apps. Wrong SDK/NDK path or version in Unity can break the build or cause native crashes on the headset.

Manifest and permissions:
Meta Quest apps need specific permissions and intent filters. If the generated AndroidManifest is wrong (e.g. after removing or changing the XR package), the app may not start or may not get input.

Solution 1: Match Unity and Meta Package Versions (Recommended First Step)

Step 1: Check Unity Version

  1. In Unity, go to Help → About Unity.
  2. Note your exact version (e.g. 2022.3 LTS, 6000.0.x).
  3. Open Meta Quest developer docs – Unity and confirm your Unity version is in the supported list for the SDK version you use.

If you are on an unsupported Unity version, either upgrade/downgrade Unity to a supported LTS or install the Meta package version that matches your Unity (e.g. an older OVR/Meta XR All-in-One build).

Step 2: Reinstall or Upgrade the Meta XR Package

  1. Open Window → Package Manager.
  2. If you see Meta XR All-in-One SDK or Meta XR SDK (or Oculus XR), note the version.
  3. Either:
    • Upgrade: Use "Update to X.X.X" if available and your Unity is supported.
    • Reinstall: Remove the package (or delete the package from Packages/manifest.json and the package folder), then add it again via Add package by name or the Meta/Oculus registry.

After changing the package, let Unity reimport and fix any Assembly Definition or script errors. Restart Unity if the Project Settings → XR Plug-in Management still does not show the Meta plug-in.

Verification

  • In Edit → Project Settings → XR Plug-in Management, you should see Meta XR (or Oculus) under both PC and Android with a checkmark when selected.
  • No red errors in the Console related to OVR, Meta, or XR.

Solution 2: Enable Meta XR for Android and Set Correct Runtime

Step 1: Enable the Meta Plug-in for Android

  1. Go to Edit → Project Settings → XR Plug-in Management.
  2. Open the Android tab (not just PC).
  3. Enable Meta XR (or Oculus) so the checkbox is on.
  4. If you use OpenXR, ensure the Meta Quest feature set is enabled and Meta XR is the active runtime for Android if required by the SDK version.

Step 2: Set Android Build Settings

  1. Go to File → Build Settings.
  2. Select Android and switch the platform if needed.
  3. Click Player Settings and under Other Settings:
    • Set Minimum API Level to at least the level required by Meta (e.g. 29+ for Quest 2/3).
    • Set Target API Level as recommended by Meta docs.
  4. Under XR Settings (or Player → XR) ensure Virtual Reality Supported is on and the SDK is listed.

Verification

  • Build a minimal scene (e.g. empty or a cube) to the Quest. If the build succeeds and the app launches (even to a static frame), XR and Android are wired correctly.

Solution 3: Fix Android SDK/NDK and Gradle

Step 1: Point Unity to Correct Android SDK and NDK

  1. Go to Edit → Preferences (Windows) or Unity → Settings (Mac).
  2. Open External Tools.
  3. Set Android SDK and Android NDK to the paths used for Android development (often from Android Studio).
  4. If you use a specific NDK version for Quest, set NDK to that version’s folder.

Step 2: Resolve Gradle Errors

If the build fails with Gradle or "Duplicate class" / "SDK version" errors:

  1. In Player Settings → Publishing Settings, try Custom Base Gradle Template and Custom Main Gradle Template only if the Meta SDK docs require it; otherwise leave default first.
  2. Ensure you do not mix multiple XR/OVR packages that ship conflicting Android dependencies (e.g. two different OVR or OpenXR Android libs). Prefer a single Meta/OVR stack per the official setup.
  3. Clean the build: delete the project’s Library and Temp (or use a fresh clone) and rebuild, or build to a new folder.

Verification

  • Build and Run to the Quest completes without Gradle or "merge" errors. The app appears on the device and launches.

Solution 4: Black Screen or Crash on Device

If the app builds and installs but shows a black screen or crashes on launch:

  1. First scene: Ensure the first scene in Build Settings has a camera and that your XR rig (OVR Camera Rig or equivalent) is present and enabled. A scene with no camera or disabled XR can show a black screen.
  2. Runtime permissions: Check that the Android manifest (generated or custom) includes any permissions required by Meta (e.g. for hand tracking). Missing permissions can cause a crash on startup.
  3. Logs: Enable Developer mode on the Quest and use adb logcat or Meta’s tools to capture the crash reason (e.g. missing native library, Java exception). That will point to a specific fix (e.g. ABI, min SDK, or missing dependency).

Verification

  • App launches to your first scene and you see the Unity/Meta XR environment (or your scene) in the headset; input (controllers or hands) is detected if you have set it up.

Prevention Tips

  • Pin Unity and SDK versions: Use a Unity LTS and a specific Meta XR/Meta Reality SDK version that are documented as compatible. Avoid upgrading both at once; upgrade one and verify before the other.
  • Use a clean project for upgrades: When moving to Meta Reality SDK 3.0, try a new project and a minimal scene first to confirm the pipeline works, then bring in your content.
  • Keep Android toolchain updated: Use a supported Android SDK/NDK set; Meta’s docs often call out recommended versions.

Related Problems and Links

For the latest supported Unity and SDK versions, always check Meta’s Unity documentation and the release notes for Meta Reality SDK 3.0.

Bookmark this fix for quick reference when setting up or upgrading Meta VR in Unity. If you’re still stuck, capture the exact error from the Console and from adb logcat and use it to search Meta’s developer forums or our other game engine help articles.