Symptom index
Find what you're seeing, jump to the fix. Each entry links to the canonical page for that problem. The optional adl-doctor.sh script diagnoses the whole chain automatically and names the failing link.
Installing apps
| Symptom | Where to go |
|---|---|
| APK install silently blocked on Samsung (One UI 6+) | Termux:X11 — Samsung Auto Blocker |
| "App not installed" / signatures do not match | Install Termux — sources — never mix F-Droid/GitHub/Play builds; uninstall all Termux apps and reinstall from one source |
| "Install unknown apps" permission missing | Grant it to your browser: Settings > Apps > (browser) > Install unknown apps; revoke afterwards |
Termux
| Symptom | Where to go |
|---|---|
[Process completed (signal 9)] — session dies in background | Android 12+ phantom-process limits: exempt Termux from battery optimization; advanced ADB mitigations (optional, with risks) in Termux troubleshooting |
Unable to locate package / package not found | Run pkg update first; for Termux:X11 packages enable the repo: pkg install x11-repo |
| Mirror/repository errors | termux-change-repo, pick another mirror (Termux troubleshooting) |
| Termux closes unexpectedly | Battery optimization + Termux troubleshooting |
Display
| Symptom | Where to go |
|---|---|
| Black screen (with or without cursor) in Termux:X11 | Display troubleshooting — session/DISPLAY/--shared-tmp checks, then the documented -legacy-drawing flag |
| Red and blue colors swapped | Display troubleshooting — documented -force-bgra flag |
| Desktop exits immediately / D-Bus errors | Display troubleshooting — install dbus-x11, start via dbus-launch --exit-with-session … |
| Tiny text / wrong scaling | Display troubleshooting — -dpi flag and desktop scaling |
| Wrong resolution on external monitor | Display troubleshooting |
| External monitor shows no signal | External displays — DP Alt Mode, cable, and hub power checks |
| Session works on phone but not external display | External displays |
| Session freezes / dies when backgrounded | Battery optimization + phantom processes (Termux troubleshooting) |
Input
| Symptom | Where to go |
|---|---|
| No keyboard input in the session | Display troubleshooting; with no physical keyboard use Termux:X11's on-screen input |
| Mouse not detected | Check Android sees it (pointer appears); then peripherals |
| Alt-Tab / shortcuts trigger Android instead of Linux | Remap in the desktop, or adjust Termux:X11 preferences / DeX keyboard settings |
| Wired keyboard dead through a single-port connection | The port is occupied by the display — use a hub or Bluetooth (USB-C hubs) |
Audio
| Symptom | Where to go |
|---|---|
| Desktop works, no sound | Audio troubleshooting — PulseAudio forwarding is a required one-time setup, not automatic |
| Volume plugin appears disconnected | Audio troubleshooting |
| No sound on Android 16 specifically | Known open upstream issue — see Audio troubleshooting |
| HDMI/monitor audio silent | Android controls output routing — Audio troubleshooting |
Browsers
| Symptom | Where to go |
|---|---|
| Firefox won't launch / crashes / renders black | Disable hardware acceleration — Web browsers |
apt install firefox on Ubuntu installs nothing usable | It's a Snap stub; use Mozilla's apt repo — Web browsers |
| Chromium refuses to start ("--no-sandbox") | Run as a non-root user; never adopt --no-sandbox — Web browsers |
| Warned about running as root | Create a normal user — What Linux on Android means |
System
| Symptom | Where to go |
|---|---|
| "No space left on device" mid-install | Free space, then dpkg --configure -a && apt --fix-broken install (Recovery) |
Could not get lock /var/lib/dpkg/… | Interrupted install — Recovery |
| Network/DNS errors inside the distro | Network troubleshooting |
| Cannot access Android storage from Linux | Run termux-setup-storage in Termux first (file management) |
| Desktop is very slow | Performance |
| Phone gets hot / throttles | Performance — sustained charging sessions are the main cause |
Summary
Match the symptom, follow the canonical page. If several things are broken at once, run adl-doctor.sh and fix the first FAIL it reports.