Android Troubleshooting
Diagnostic Phases
| Phase | Manifestation | Primary Inspection |
|---|---|---|
| Installation | Parse error, app crash on open | CPU architecture, signing keys |
| Deployment | Stalled on Checking / Downloading / Extracting | Network, storage capacity, ABI matching |
| Startup | Runtime fails to boot | Logcat traces, WebUI readiness |
| Activation | Paired successfully but service not running | USB debugging confirmation, port 5555 |
| Execution | Virtual display renders black, clicks fail | Privileged service status, screenshot backend |
| Backgrounding | Tasks stop when display sleeps | Battery optimization exemptions, keep-alive settings |
| Updates | Hot-update fails, crash on boot | Transaction logs, rollback recovery |
Installation & Deployment
| Symptom | Root Cause | Remediation |
|---|---|---|
| Parse error on install | Corrupted APK or mismatched architecture | Re-download package matching device ABI |
| Instant crash on launch | 32-bit device or incompatible ABI | Requires 64-bit ARM or x86_64 hardware |
Status NotBundled | Thin APK used without release support | Switch to Full APK |
Status LowDisk | Free storage is below 2 GB | Free internal disk space |
| Download stalled | Mirror returned challenge page or proxy block | Switch download mirror |
| Checksum validation failed | Corrupted download or mirror divergence | Delete partial file and retry |
| Extraction failed | Storage exhausted or interrupted | Retry; switch to Full APK if failures persist |
Initial WebUI Startup Delays
Pre-compiled __pycache__ is stripped from distribution packages. Initial bytecode compilation can take upwards of 90 seconds. The warning WebUI not ready within 90000ms is expected behavior.
Permissions & Activation
| Symptom | Root Cause | Remediation |
|---|---|---|
| Paired but service not running | USB debugging dialog was not confirmed | Re-pair and check "Always allow from this computer" |
| Activation lost after reboot | adbd permissions reset on boot | Re-pair via wireless debugging (expected OS behavior) |
| Binder timeout | Privileged process terminated by battery saver | Disable battery optimization; retry |
| External Shizuku unreachable | Manager app stopped or permission revoked | Open manager app and re-grant permissions |
| Crash on MediaTek devices | Custom OEM ROM class injection | Context-only initialization is active; submit logs if issue persists |
| Reconnection fails after network change | Debugging session cleared by OS | Re-activate wireless debugging |
Virtual Displays & Screen Streaming
| Symptom | Root Cause | Remediation |
|---|---|---|
| Automation view renders black | Privileged service inactive | Verify activation status |
| Video renders but clicks fail | Control backend not set to azurpilot_android | Set control method to Android host backend |
| Frozen frame capture | Game application hung | Restart game / instance |
| Game appears on physical screen | Virtual display creation failed | Verify virtual display allocation in logs |
| Login dialog appears on main screen | OEM redirect behavior | Handled by SdkTaskRepatriator; dismiss manually if needed |
Background Termination
| Clue | Root Cause | Remediation |
|---|---|---|
| Logs abruptly truncate | Process killed by OS low-memory killer | Set Battery Optimization to Unrestricted |
| Halts minutes after display sleeps | Vendor battery saver | Add app to vendor Autostart and Background whitelists |
| Occurs only on specific vendor ROM | Proprietary vendor task killer | Configure vendor-specific background policies |
| Foreground notification disappears | Foreground service killed | Restart Runtime |
Hot-Updates & Full Updates
| Symptom | Root Cause | Remediation |
|---|---|---|
| Hot-update prompts that full update is required | uv.lock modified upstream | Execute full Runtime update |
| Crash following hot-update | Rollback failed | Inspect config/android-update-transaction.json |
| Frontend compilation timeout | Hardware or storage constraints | Retain existing release and retry later |
| Configurations missing after full update | Interrupted deployment | Restore config/ from backup |
| App update fails to install | Signature mismatch | Uninstall old version (export settings first) |
Collecting Logs
bash
adb logcat -v time --pid=$(adb shell pidof com.azurpilot.ghio)
adb shell tail -n 200 /sdcard/Android/data/com.azurpilot.ghio/files/log/proot/session.log
adb forward tcp:25548 tcp:25548Export logs via "Settings → Logs → Export" to generate a diagnostic zip archive.