# Errors

Every exception the client raises, and the codes and reasons they carry. Guide:
[Errors](../../guide/errors.md).

## <kbd>module</kbd> `tap_e2e.errors`
Exception hierarchy. Driver failures arrive as data (CommandResult.error) and become CommandError; server-level failures arrive as gRPC status codes and are mapped in client.py. 

**Global Variables**
---------------
- **TYPE_CHECKING**

---

### <kbd>class</kbd> `TapError`
Base class for everything this package raises deliberately. 

---

### <kbd>class</kbd> `ServerError`
The host server rejected or failed a call (unknown connection or device, bad argument, driver start failure, ...). ``code`` is the gRPC status code name; ``reason`` is the server's structured ``FailureReason``, ``FailureReason.UNSPECIFIED`` when the failure did not come from the daemon. 

### <kbd>method</kbd> `ServerError.__init__`

```python
__init__(
    code: 'str',
    details: 'str',
    reason: 'FailureReason' = <FailureReason.UNSPECIFIED: 'UNSPECIFIED'>
)
```

---

### <kbd>class</kbd> `CommandError`
A driver command's outcome was ``error``. ``code`` is an ErrorCode; ``detail`` refines it (e.g. NOT_FOUND/END_REACHED); TRANSPORT_LOST/INDETERMINATE carry the transmission state. 

### <kbd>method</kbd> `CommandError.__init__`

```python
__init__(
    code: 'ErrorCode',
    detail: 'str | None',
    driver_message: 'str | None',
    operation: 'str',
    serial: 'str',
    selector: 'str | None',
    request_id: 'int',
    generation: 'int',
    duration_ms: 'int'
)
```

---

### <kbd>class</kbd> `WaitTimeoutError`
A condition did not hold within its timeout; the message names the device, the condition and what was observed so a log line alone is diagnosable: ``reason`` and ``match_count`` for the waits the device runs (``visible``, ``one``, ``gone``, ``App.await_visible``, ``App.await_screen_stable``), ``last_observation`` and ``polls`` for the ones the client polls. 

### <kbd>method</kbd> `WaitTimeoutError.__init__`

```python
__init__(
    description: 'str',
    serial: 'str',
    elapsed_ms: 'int',
    polls: 'int' = 0,
    last: 'str | None' = None,
    reason: 'WaitReason | None' = None,
    match_count: 'int | None' = None
)
```

---

### <kbd>class</kbd> `AppLifecycleError`
Install/launch/stop did not reach the verified end state. 

---

### <kbd>class</kbd> `DeviceBusyError`
Another session — in this process or any other — holds the device, and ``wait_for_device`` was zero or ran out. The device is fine; try later or pick another serial. 

---

### <kbd>class</kbd> `DeviceQuarantinedError`
The device's session journal keeps it out of service (a mutation whose outcome could not be proven, a corrupt journal, an uncertain ADB cleanup). It stays unusable until an explicit reset; retrying or waiting does not help. 

### <kbd>method</kbd> `DeviceQuarantinedError.__init__`

```python
__init__(serial: 'str', details: 'str')
```

## <kbd>class</kbd> `ErrorCode`
Why a driver command failed (``CommandError.code``). ``UNKNOWN`` also stands for a code this client version does not know. 

## <kbd>class</kbd> `FailureReason`
The server's structured reason for a failed call (``ServerError.reason``). ``UNSPECIFIED`` means the failure did not come from the daemon (a transport failure, a proxy, a cancelled call) or carried a reason this client version does not know. 

## <kbd>class</kbd> `WaitReason`
Why a device-side wait timed out (``WaitTimeoutError.reason``).