Troubleshooting
Start with the error code and hints Olef returns. Keep the original failure and relevant evidence before changing the environment.
olef doctor --jsondoctor --fix can repair setup, but it changes the environment. Read the diagnosis first.
No device, unauthorized device, or several devices
Section titled “No device, unauthorized device, or several devices”Run olef devices. Start the emulator if it is not running. For a phone, enable USB debugging and accept its authorization prompt. Check the cable and Android Platform Tools installation. With multiple devices, pass --device using the returned serial.
If using Cloud, inspect olef cloud status instead of installing a local Android SDK as a workaround. Confirm the project is linked to the intended workspace.
Connection fails
Section titled “Connection fails”Check olef --version and olef doctor --json. Confirm that the machine can download the matching release assets and that the device is online. Follow the returned repair hints, then retry olef connect.
For updates, use the instructions printed by olef update, then refresh the agent integration with olef init.
The agent cannot find Olef
Section titled “The agent cannot find Olef”Confirm the agent’s shell can run olef --version. A CLI installed in your interactive terminal may not be on another process’s PATH. Run olef init in the intended environment and start a new agent session. See agent setup.
A tap fails or has an uncertain result
Section titled “A tap fails or has an uncertain result”Read a fresh ui dump; choose a selector from that screen. Check for disabled, covered, ambiguous, or offscreen elements. If the input was delivered but the result is unknown, inspect before retrying: repeating a tap can submit a form twice.
An app stopped at a breakpoint may not respond to a tap. Inspect olef debug status and resume deliberately. See debugging.
device_reserved
Section titled “device_reserved”Another session owns the device. Use the intended session token, ask the owner to finish, or select another device. Do not bypass ownership simply to make a command succeed. Read sessions.
UiAutomationService ... already registered!
Section titled “UiAutomationService ... already registered!”Another instrumentation tool needs the same slot as Olef. Wrap that command:
olef test -- ./gradlew connectedDebugAndroidTestDebugger cannot attach
Section titled “Debugger cannot attach”Check that the installed app is debuggable, the correct process is selected, and another debugger is not attached. For native mode, check NDK/LLDB and ABI readiness with the diagnostics. Missing Compose runtime data can also be a compatibility or attachment issue.
HTTPS capture is empty or the app reports TLS errors
Section titled “HTTPS capture is empty or the app reports TLS errors”Check proxy status, host filters, app CA trust, certificate pinning, and whether the app uses the system proxy. Follow the network guide. After olef net stop, inspect any unresolved cleanup and verify an actual app request.
Cloud sign-in, access, or capacity fails
Section titled “Cloud sign-in, access, or capacity fails”Use olef cloud whoami and olef cloud status. Confirm the account, organization, enabled access, and linked workspace. The dashboard shows account limits, usage, and session state. A waitlisted account needs access before starting Cloud work; a capacity error may need a later retry or the options offered by the dashboard.
A recorded test fails
Section titled “A recorded test fails”Open its HTML report and inspect the first failing step, screenshot, and error. Check starting app data, permissions, backend state, and selectors. Do not remove a meaningful assertion just to make the test pass. See test runs.
Ask for help with evidence
Section titled “Ask for help with evidence”olef collect creates a diagnostic bundle from available evidence. Review and redact sensitive data before sharing it; screenshots and recordings need particular care. Include the CLI version, environment, exact failure, and steps to reproduce when reporting an issue.