undefined

If `metavr device list` returns no devices, check the USB cable, developer mode, and ADB authorization.

metavr device list
metavr device info <device_id>

metavr app list

undefined

Put on the headset and reproduce the issue. The logs stream in real time to your terminal. Press Ctrl+C to stop.

undefined

undefined

metavr app stop com.example.myapp
metavr app launch com.example.myapp
metavr log --tag Unity --level W

App crashes on launch
├── Does `metavr app launch <pkg>` show "Error: Activity not found"?
│   └── YES → Package name is wrong or app is not installed.
│       Run `metavr app list` to verify the correct package name.
├── Does logcat show `FATAL EXCEPTION` in the first 5 seconds?
│   ├── YES, with `ClassNotFoundException` or `NoClassDefFoundError`
│   │   └── Missing native library or wrong ABI. Check the APK is built for ARM64.
│   │       Run: `metavr adb shell getprop ro.product.cpu.abi` → must show "arm64-v8a"
│   ├── YES, with `SecurityException` or `Permission denied`
│   │   └── Missing manifest permission. Check the logcat message for which permission.
│   │       Common: hand tracking, scene, camera permissions not declared.
│   └── YES, with `NullPointerException` or other Java exception
│       └── Application code bug. Read the stack trace for the failing class and method.
├── Does logcat show `native crash` / `SIGSEGV` / `SIGABRT`?
│   ├── Check if the crash is in a Unity/Unreal library (libunity.so, libUE4.so)
│   │   └── Engine bug or incompatible SDK version. Check Meta XR SDK release notes
│   │       for known issues with your engine version.
│   └── Check if the crash is in your own native code
│       └── Debug with `metavr adb logcat --buffer crash` for the tombstone, then use
│           `addr2line` or `ndk-stack` on the crash address.
└── No crash visible in logs?
    └── Check if the app is being killed by the system.
        Run: `metavr adb logcat --tag ActivityManager --level W`
        Look for "Force stopping" or "Process died" messages. Common cause: OOM killer
        triggered by excessive memory usage on launch.

App freezes or ANR dialog appears
├── Does logcat show "ANR in <package>"?
│   ├── YES, with "Reason: Input dispatching timed out"
│   │   └── The main/UI thread is blocked. Check for:
│   │       - Synchronous network calls on the main thread
│   │       - Large file I/O on the main thread
│   │       - Deadlocks between threads
│   │       Run: `metavr adb shell kill -3 <pid>` to dump thread stacks, then
│   │       `metavr files pull /data/anr/traces.txt ./` to retrieve the ANR trace.
│   └── YES, with "Reason: executing service"
│       └── A background service is taking too long. Check the service implementation.
└── No ANR, but app appears frozen?
    ├── Is the render loop still running? (Check VrApi logs for frame submission)
    │   ├── YES → The app is rendering but not processing input. Check input system.
    │   └── NO → The render thread is blocked or crashed silently.
    │       Check: `metavr adb logcat --tag VrApi` for "FPS" lines stopping.
    └── Is the device overheating?
        Run: `metavr device battery` — if battery temperature > 40°C, thermal
        throttling may have halted the app. Let device cool down and retry.

Black screen after app launch
├── Is the app actually running?
│   Run: `metavr adb shell pidof <package>` — if empty, app crashed silently.
│   └── Check crash logs: `metavr adb logcat --buffer crash`
├── Is VrApi initialized?
│   Check: `metavr adb logcat --tag VrApi | grep "VrApi" | head -20`
│   ├── No VrApi output → XR session never started. Check OpenXR/OVR initialization code.
│   └── VrApi output exists → Frames are being submitted but may be empty.
│       └── Check: rendering pipeline, camera setup, shader compilation errors.
├── Unity-specific: "Shader compiler" or "Compiling shaders" in logs?
│   └── Shader warmup can cause a black screen for several seconds on first launch.
│       Use shader prewarming/variant preloading to avoid this.
└── Is the correct rendering API being used?
    Check: `metavr adb logcat --tag Unity --level E` for Vulkan/GLES errors.
    Quest requires OpenGL ES 3.0 minimum. Vulkan is preferred on Quest 3.

App stutters or drops frames
├── Check current FPS:
│   `metavr adb logcat --tag VrApi | grep FPS`
│   ├── FPS consistently below 72 → GPU or CPU bottleneck.
│   │   ├── Check GPU: use Perfetto or OVR Metrics Tool. Look for GPU completion
│   │   │   time > 13.8ms (72Hz) or > 11.1ms (90Hz).
│   │   └── Check CPU: look for game thread or render thread exceeding frame budget.
│   └── FPS mostly stable but periodic drops
│       ├── Check for GC pauses: `metavr adb logcat --tag dalvikvm --level D`
│       │   or `metavr adb logcat --regex "GC_|clamp"` → reduce allocations per frame.
│       ├── Check for thermal throttling: `metavr adb logcat --tag ThermalService --level W`
│       │   → sustained heavy load causes CPU/GPU frequency reduction.
│       └── Check for asset loading on main thread: large textures or models loaded
│           synchronously will cause frame spikes. Use async loading.
└── Only stutters in specific scenes?
    └── Profile that scene. Common causes: too many draw calls (>100), unculled
        off-screen geometry, expensive shaders, excessive overdraw, uncompressed textures.

Controllers or hands not tracking correctly
├── Are controllers paired and connected?
│   `metavr device info <id>` — check controller connection status.
├── Is hand tracking enabled in device settings?
│   Check: Settings > Movement Tracking > Hand and Body Tracking.
├── Does the app request the correct tracking mode?
│   ├── For hand tracking: manifest must include
│   │   `com.oculus.permission.HAND_TRACKING` and
│   │   `com.oculus.handtracking.frequency` set to "HIGH" if needed.
│   └── For controller tracking: ensure the app is not forcing hand-tracking-only mode.
└── Tracking works but is jittery or delayed?
    ├── Check lighting: tracking cameras need adequate, even lighting. Very bright
    │   or very dim environments degrade tracking quality.
    └── Check for occlusion: hands or controllers held outside the tracking camera
        FOV will lose tracking. The camera FOV is approximately 110 degrees.

No audio or wrong audio output
├── Is audio playing through the headset speakers?
│   └── Check: Settings > Sound — ensure headset speakers are selected, not Bluetooth.
├── Does the app use spatial audio?
│   ├── Check for FMOD/Wwise initialization errors in logcat.
│   └── Check that audio sources have correct 3D settings and are not muted.
├── Audio is distorted or crackling?
│   └── Audio buffer underruns. Check for CPU overload causing audio thread starvation.
│       Reduce audio complexity or increase buffer size.
└── Audio plays from wrong position?
    └── Check spatial audio source positions match visual object positions.
        Common issue: audio listener not attached to the camera/head transform.

undefined

Filter by tag to focus on specific subsystems:

```bash
metavr adb logcat --tag VrApi
metavr adb logcat --tag Unity

undefined

See [logcat-filtering.md](references/logcat-filtering.md) for a full guide on log filtering techniques.

metavr log | grep -i "fatal\|crash\|exception\|anr"

undefined

See [common-issues.md](references/common-issues.md) for a catalog of known issues and their solutions.