Troubleshooting

Start with `sarab info`

sarab info

It checks the host (binder, sub-ids, GPU, AppArmor, Wayland, tools), shows the versions and every directory Sarab uses, and says whether Android is running. Anything it marks as missing comes with the command that fixes it. Include its output in every bug report.

Android does not start

“binderfs is in this kernel’s binder_linux module, which is not loaded.” Load it now and at every boot:

sudo modprobe binder_linux && echo binder_linux | sudo tee /etc/modules-load.d/sarab.conf

“this kernel has no binderfs.” Android cannot run on this kernel. It needs CONFIG_ANDROID_BINDERFS, built in or as a module.

“missing host tools”. Install the packages it names. See Requirements.

“pasta is not installed, and without it Android has no network.” Install the passt package. To boot without a network on purpose, run sarab start --foreground --no-network.

A GPU error. Android needs a GPU that Mesa drives: AMD, Intel, or NVIDIA with nouveau. With NVIDIA’s proprietary driver there is no way to run it yet. If the render node is “open only to you and its group”, install the udev rule Sarab prints (Requirements). On a machine with several GPUs, choose one with SARAB_RENDER_NODE=/dev/dri/renderD129.

An AppArmor error (Ubuntu 23.10 and later). Install the profile:

sarab apparmor-profile | sudo tee /etc/apparmor.d/sarab-ns >/dev/null && sudo apparmor_parser -r /etc/apparmor.d/sarab-ns

“runtime exited before it finished booting” or “boot did not complete”. Look at Android’s kernel log, which is where its init writes:

sarab logs --kernel

“Sarab is not set up yet”. Setup asks questions, so it runs only in a terminal: run sarab start there once. Clicking an app or starting the unit before that fails with this message.

An app window does not appear

Check that Android is up: sarab status.
Look at the host services’ log, which carries Android’s display: sarab logs --hostd.
On a tiling compositor other than Hyprland and sway, the window may be tiled somewhere unexpected. Add a float rule for app ids starting with waydroid. (Windows).
On GNOME, the window has no title bar. It is there: use Super+drag to move it and Alt+F4 to close it.
If you opened an app from a notification and the window closed, the screen can stay empty. Open the app you want again from the launcher.

An app will not install

Sarab explains Android’s refusal in words; Installing apps lists the common ones. The one you will meet most is an app built for ARM processors only, which cannot run until Sarab has a translation layer.

No sound, or a video will not play

Media decoding does not work in the current Android image, so apps that play audio or video through Android’s media framework fail. A fix is being worked on. See Limitations.

Register the device first (Google Play), wait a few minutes, then sarab restart. Until then, Google Play services keeps posting a reminder, with a sound.

Notifications or the clipboard do not work

Both are served by sarab-hostd, which runs without a service it cannot start and says so in its log:

sarab logs --hostd

Notifications need a notification daemon on the session bus when Android starts. One that starts later is not picked up until the next start: sarab restart.
The clipboard needs wlr-data-control or wl-clipboard (Windows). With the systemd unit, it also needs your Wayland session’s environment: systemctl --user import-environment WAYLAND_DISPLAY.

Removing an app closed my other apps

That is a known issue in the image: Android restarts its system services after an uninstall. sarab app rm waits for them to come back. Open your apps again.

Reporting a bug

Open an issue on GitHub with:

the output of sarab info;
your distribution, desktop and compositor, and your GPU;
what you did, what you expected, and what happened;
the relevant log: sarab logs --kernel, sarab logs --hostd, sarab logs --daemon, or sarab logs -n 300.

Report a security issue privately instead, as Security describes.