# Troubleshooting

Source: https://olef.dev/docs/troubleshooting

Start with the error code and hints Olef returns. Keep the original failure and relevant evidence before changing the environment.

```bash
olef doctor --json
```

`doctor --fix` can repair setup, but it changes the environment. Read the diagnosis first.

## 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

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

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](https://olef.dev/docs/start/agents).

## 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](https://olef.dev/docs/concepts/debugging).

## `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](https://olef.dev/docs/concepts/sessions).

## `UiAutomationService ... already registered!`

Another instrumentation tool needs the same slot as Olef. Wrap that command:

```bash
olef test -- ./gradlew connectedDebugAndroidTest
```

## 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

Check proxy status, host filters, app CA trust, certificate pinning, and whether the app uses the system proxy. Follow the [network guide](https://olef.dev/docs/concepts/network). After `olef net stop`, inspect any unresolved cleanup and verify an actual app request.

## 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

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](https://olef.dev/docs/concepts/test-runs).

## 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](https://github.com/olef-dev/olef/issues).