Troubleshooting

Device not appearing in Studio

Always start at the adb layer, if adb cannot see the phone, nothing above it can:

adb devices
# List of devices attached
# R58M12ABCDE     device

• No device listed: try a different USB cable first (charge-only cables are the top cause), then a different port. Confirm USB debugging is enabled.
• adb not recognized: install platform-tools, or set the ADB path in Studio Settings, usually C:\Users\<you>\AppData\Local\Android\Sdk\platform-tools\adb.exe.
• Listed but Studio does not show it: restart the adb server (below) and reopen the Devices panel.

adb kill-server
adb start-server
adb devices

The adb reset. Clears stale server state and stuck sessions.

Device shows as “unauthorized”

The phone has not authorized this computer. Unlock the phone and tap Allow on the “Allow USB debugging?” dialog. If the dialog refuses to appear: unplug, replug, and check Developer Options is still enabled. As a last resort, tap Revoke USB debugging authorizations in Developer Options and reconnect, this forces a fresh prompt.

Companion install blocked by Android

• Enable Developer Options → Install via USB, several vendors (Xiaomi MIUI in particular) gate sideloads behind this switch, then retry Install from Studio.
• If a previous Companion version is installed, uninstall it from the phone’s app settings first; signature or version conflicts block the update path.
• Check free storage on the device, silent install failures on full phones are common.

Live mirror shows a black screen or permission prompt

OrbiStream uses Android’s MediaProjection API, so the first capture triggers a system permission dialog on the phone, approve it there. If the stream stays black after approval:

1. Click Ping in the Devices panel to confirm the Companion bridge is alive.
2. Close and reopen the Live panel to restart the stream.
3. Check whether the foreground app blocks capture: banking apps, DRM video, and some secure screens set FLAG_SECURE, and Android hardware-blocks capturing them. That black rectangle is the OS, not a Studio bug.

No logs in the Logs panel

Almost always a filter excluding everything. Widen step by step: set severity to Info+ or All levels, set the time range to All buffered, then clear the package, tag, and text fields. If the panel warned that the package PID lookup failed, the app probably is not running, launch it on the device and regenerate logs.

adb logcat -c   # optional: clear the buffer, then reproduce the issue for a clean capture

Test runs fail before any step executes

• Run orbittest doctor in the project, it checks Node, adb, and device visibility from the test process’s point of view.
• Confirm the device is selected in the Devices panel and shows state device in adb devices.
• Screen must be on and unlocked for UIAutomator: start tests with await orbit.wakeUp().
• A system dialog (permission prompt, crash dialog, low-battery warning) covering the app makes UIAutomator dumps fail or taps land wrong, dismiss it and rerun.
• If tests pass in a terminal but fail from Studio, compare environments: Studio injects DEVICE_SERIAL, ADB_PATH, and PROJECT_ROOT; a terminal session might use different values.

Windows SmartScreen blocks the installer

Expected for an unsigned installer: click More info, then Run anyway. Verify the file first against the published SHA256 so you know the download is genuine, the exact steps are on Installer Integrity.

Frequently asked questions

The mirror works but taps from tests miss their targets.

Usually a stale hierarchy: the screen changed after the dump. Add a wait for the target (waitForId) before tapping, and check the Inspector to confirm the element’s bounds are what you think.

Everything worked yesterday and nothing does today.

Phone OS updates can silently disable Developer Options or revoke authorizations. Verify USB debugging is on, reauthorize the PC, and run the adb reset sequence.

Where do I report a bug?

The GitHub issues page for the relevant repository, Studio issues on the Studio download repo, framework issues on the OrbitTest repo. Include orbittest doctor output and the run artifacts.

Related pages

• Installation — Install Orbittest Studio on Windows, enable USB debugging on Android, and deploy the Companion app, step by step.
• Mobile Testing — Android automation with ADB and UIAutomator through @orbittest/mobile: setup, configuration, hybrid tests, and evidence.
• Installer Integrity — Verify the Studio installer with its published SHA256 hash before running it, and follow safe download practices.
• Quick Start — From new project to first passing mobile test: connect a device, write a smoke test, run it, and review the video evidence.