's'

README.md

@@ -135,13 +135,24 @@ If you still see `unauthorized` after an upgrade, stop the container, remove per
 rm -rf ~/data-redroid13/misc/adb
 ```
 
+## ADB `failed to connect` / connection refused
+
+This means **nothing is listening on the host port** (not the same as `unauthorized`). Typical causes:
+
+1. **Container exited** — especially with `--rm`, a crash removes the instance. Run `docker ps -a` and `docker logs` on a **non-`--rm`** run (`--keep-container`) to see init/EGL errors.
+2. **`androidboot.redroid_gpu_mode=host`** — Mesa/EGL or DRI inside the guest can fail on some hosts; Android never reaches **adbd**. **Workaround:** force software rendering:
+   ```bash
+   python run_redroid.py ... --adb-insecure --gpu-mode guest
+   ```
+3. **Still booting** — wait longer, or use **`--wait-tcp 90`** on `run_redroid.py` to block until TCP opens and print logs if it does not.
+
 ## Black screen or flickering
 
 With **`--gpu-mode guest`** (or **`auto`** when no `/dev/dri` exists), the display uses **software GLES** (SwiftShader). On many **headless servers**, SurfaceFlinger may show a **black screen**, **flicker**, or very low FPS. That is a **display stack** issue, not ADB. The default **`auto`** mode uses **host** GPU when DRI nodes are visible and injects **`--device`** flags automatically.
 
 **What to try**
 
-1. **GPU on the host:** ensure **`--gpu-mode auto`** (default) so DRI is detected, or set **`--gpu-mode host`** explicitly. If you must pass devices manually (unusual when `auto` works), for example:
+1. **GPU on the host:** **`--gpu-mode auto`** (default) enables **host** when `/dev/dri` exists. If the instance **crashes** or **ADB never connects**, host EGL may be incompatible — fall back to **`--gpu-mode guest`**. If you must pass devices manually, for example:
    ```bash
    docker run ... --device /dev/dri ...
    ```