Waydroid troubleshooting and FAQ

Scope and prerequisites#

Commands and output are generic examples. Kernel, image, package, and service versions affect the exact behavior; check the documentation for the versions you use as you read.

Back up Android data and stop the relevant sessions before changing containers, images, mounts, or firewalls. Examples that delete data or force a stop may cause data loss. Manage NixOS system and user-environment configuration through Nix. Generic Linux instructions using apt/pacman, writing directly to /etc, or installing with pip do not apply to the NixOS host. The build, test, and switch phases of a rebuild, and functional verification after startup, are separate stages.

This guide covers the most common Waydroid failures in three steps: diagnosing symptoms, analyzing root causes, and providing reproducible repair commands. Diagnostic examples are retained for each category. Before applying a fix, confirm the cause, versions, data backups, and permission boundaries; do not blindly execute every command in sequence.

Container startup failures#

Service manager /dev/binder has died

Symptoms: waydroid session start exits immediately, and the log shows Service manager /dev/binder has died.

Root cause: this log indicates that the Binder service manager disappeared, potentially because the container exited or because of image, driver, or resource problems. Check the LXC and Android logs first. Missing PSI is a separate host-configuration check; this message does not directly establish that Binder depends on PSI.

Solution:

Step 1 — check PSI; add a kernel boot parameter only if needed:

First inspect /proc/pressure/ and the kernel configuration. If PSI is already available, this change is not a necessary step for resolving that log message. Adapt boot-configuration examples to the actual bootloader; do not replace an entire existing parameter list.

# 编辑 /etc/default/grub，在 GRUB_CMDLINE_LINUX 中添加
GRUB_CMDLINE_LINUX="... psi=1"

# 更新 grub 配置
sudo update-grub        # Debian/Ubuntu
sudo grub-mkconfig -o /boot/grub/grub.cfg  # Arch

# NixOS 用户（在 configuration.nix 中）：
# boot.kernelParams = [ "psi=1" ];

Step 2 — confirm that PSI is active:

cat /proc/pressure/cpu
# 应该输出形如: some avg10=0.00 avg60=0.00 avg300=0.00 total=...

ls /proc/pressure/
# 应包含: cpu  io  memory
# 若为空 → PSI 未生效，检查内核编译选项 CONFIG_PSI=y

Step 3 — check the actual image and runtime environment

The vsyscall mapping in /proc/self/maps is not a general Waydroid verification requirement, nor is it called “vsyscall32.” Assess compatibility parameters only if a particular old binary actually fails because of that interface. Do not weaken kernel protections by default to fix Binder.

sudo waydroid logcat
journalctl -u waydroid-container -b

For custom-kernel failures, compare with a known-working kernel and the corresponding logs. Do not claim that all Zen/Liquorix kernels conflict with PSI.

Binder module not loaded

Symptoms: waydroid log reports Failed to open /dev/binder or binder: Unknown symbol.

Possible causes: Binder is unavailable or not loaded, the device nodes or permissions are incorrect, or the kernel module is mismatched. For Unknown symbol, check that the module matches the kernel.

Solution:

# 检查 binder 模块状态
lsmod | grep binder

# 如果无输出，加载传统 binder_linux 模块
sudo modprobe binder_linux

# 或加载 发行版提供的 Rust Binder（若实际可用）
sudo modprobe rust_binder

# 确认 /dev/binder 设备存在
ls -la /dev/binder*
# 应显示 /dev/binder, /dev/hwbinder, /dev/vndbinder

# 如果需要开机自动加载
echo "binder_linux" | sudo tee /etc/modules-load.d/waydroid.conf

binder_linux vs. rust_binder Check the Binder modules and device nodes actually provided by your distribution. Verify the availability and compatibility of the C/Rust implementations against the specific kernel; do not infer stability from a version number. See 01 Architecture for Binder selection.

Incompatible LXC version

Symptoms: after creation, the container stays in CREATING and never reaches RUNNING, or waydroid init reports lxc configuration error.

Root cause: the host LXC version is incompatible with the LXC configuration format in the Waydroid image.

Solution:

# 查看 LXC 版本
lxc-info --version

# 查看 Waydroid LXC 日志
sudo cat /var/lib/waydroid/lxc/waydroid/waydroid.log

# 查看容器状态
sudo lxc-ls -f | grep waydroid

# 若卡在 CREATING，尝试强制停止后重新 init
sudo waydroid container stop
# 破坏性清理示例：先停止会话/容器、核对路径和备份，再手动决定
# sudo rm -rf -- /var/lib/waydroid/lxc/waydroid
sudo waydroid init -f # 强制初始化；先核对当前状态与备份

waydroid init -f forces initialization; it does not unconditionally erase all user data. Manually deleting data directories does cause the corresponding data loss. Confirm your backups before proceeding.

systemd service not started

Symptoms: waydroid session start reports connection refused or No such file or directory.

Root cause: the waydroid-container systemd service is not running.

Solution:

# 检查服务状态
systemctl status waydroid-container

# 查看完整日志
journalctl -u waydroid-container -b --no-pager -l

# 如果服务未启用
sudo systemctl enable --now waydroid-container

# 如果服务启动后立即退出
journalctl -u waydroid-container -b -p 3  # 只看错误

Interpreting common systemd log messages:

A ZFS root filesystem causes a boot loop

Symptoms: the container repeatedly restarts (a boot loop), with no clear error in waydroid log.

Root cause: the ZFS dataset does not enable acltype=posixacl by default, while the Waydroid container requires POSIX ACL support to operate correctly.

Solution:

# 确认当前 acltype 设置
zfs get acltype <VERIFIED_DATASET>

# 若为 off，手动启用
sudo zfs set acltype=posixacl <VERIFIED_DATASET>

# 示例（假如 dataset 路径为 rpool/ROOT/nixos）
sudo zfs set acltype=posixacl <VERIFIED_DATASET> # 仅在日志/数据集条件确认后

# 重启 Waydroid
sudo systemctl restart waydroid-container
waydroid session start

For NixOS + ZFS users If Waydroid installation adds nonstandard entries to fstab, nixos-rebuild may fail. Always run nixos-generate-config before installing Waydroid to generate a correct fstab baseline. See 03 NixOS integration.

Networking problems#

No network connection inside Android

Symptoms: the Android browser cannot open web pages, but networking on the host works normally.

Root cause: Waydroid provides networking through the waydroid0 bridge + NAT + dnsmasq. A failure at any point in that chain can disconnect the network.

Diagnostic path:

# Step 1: 检查 IPv6 是否禁用（Waydroid 依赖 IPv6）
cat /proc/sys/net/ipv6/conf/all/disable_ipv6
# 按当前脚本要求核对；不是 Binder 依赖的证据

# Step 2: 检查 waydroid0 网桥是否存在
ip link show waydroid0
# 应显示 state UP。若不存在，重启 waydroid-container

# Step 3: 检查 dnsmasq 是否运行
pgrep -a dnsmasq | grep waydroid

# Step 4: 检查防火墙 FORWARD 规则
sudo nft list ruleset | grep -A5 waydroid
# 或
sudo iptables -L FORWARD -v | grep waydroid

Repair (target the failed link):

# 如果 IPv6 被禁用
sudo sysctl -w net.ipv6.conf.all.disable_ipv6=0

# 如果 waydroid0 缺失
sudo systemctl restart waydroid-container

# 如果 dnsmasq 未运行，检查端口占用
sudo ss -tulpn | grep -E ':53 |:67 '
# 若 53/67 端口被 systemd-resolved 占用，修改 /etc/systemd/resolved.conf:
# DNSStubListener=no
sudo systemctl restart systemd-resolved

For the complete network architecture, see 05 Networking and the security model.

DNS resolution fails

Symptoms: Android can ping IP addresses but cannot resolve domain names.

Root cause: the host's systemd-resolved or another DNS service occupies port 53, preventing dnsmasq from binding.

Solution:

# 确认端口占用
sudo lsof -i :53

# 方案 A：禁用 systemd-resolved 的 DNS 监听
sudo mkdir -p /etc/systemd/resolved.conf.d/
echo -e "[Resolve]\nDNSStubListener=no" | sudo tee /etc/systemd/resolved.conf.d/waydroid.conf
sudo systemctl restart systemd-resolved

# 方案 B：如果方案 A 不可行，手动在 Android 内设置 DNS
sudo waydroid shell
# 在 Android shell 中：
setprop net.dns1 <EXAMPLE_IP>
setprop net.dns2 <EXAMPLE_IP>

Docker bridge conflicts

Symptoms: Waydroid networking stops working after Docker is installed.

Root cause: Docker's docker0 bridge may conflict with the waydroid0 bridge's IP range or lxc-use-nft setting.

Solution:

# 方案 A：修改 LXC 配置，禁用 nftables
# LXC_USE_NFT 是网络脚本变量，不在 LXC config 追加无效配置；先核对实际后端
sudo systemctl restart waydroid-container

# 方案 B：调整 waydroid0 网桥 IP（避免与 docker0 <EXAMPLE_IP>/16 重叠）
# 编辑 /var/lib/waydroid/lxc/waydroid/config，修改：
# lxc.net.0.ipv4.address = <EXAMPLE_IP>/24
# lxc.net.0.ipv4.gateway = <EXAMPLE_IP>

# 方案 C：重建容器网络
sudo waydroid container stop
sudo systemctl restart waydroid-container
waydroid session start

Play Store cannot connect

Symptoms: Play Store opens with a "Try again" message or a white screen, while other applications can access the network.

Possible causes: networking/DNS, the GAPPS image, service state, or an unregistered device. The official self-certification process can address specific uncertified-device messages; lack of certification is not the only cause of every white screen.

Solution:

# Step 1: 获取 Android ID
sudo waydroid shell
# 进入 Android shell 后：
sqlite3 /data/data/com.google.android.gsf/databases/gservices.db \
  "select * from main where name = 'android_id';"
# 复制输出的数字（不带引号），然后 exit 退出 shell

# Step 2: 用浏览器打开
# https://www.google.com/android/uncertified

# Step 3: 在页面输入框中粘贴 android_id，提交

# Step 4: 等待数分钟并按页面状态检查（Google 需要时间下发认证）
# 关闭 Waydroid，服务反映更新后重启：
sudo systemctl restart waydroid-container
waydroid session start

# Step 5: 清除 Play Store 缓存
sudo waydroid shell pm clear com.android.vending # 会清除应用数据，先确认

Play Integrity API Even after Play Protect certification, Waydroid still cannot pass the Google Play Integrity API's strong checks (the corresponding integrity level). Whether an application refuses to run depends on its requirements and server-side policy. Self-certification does not mean satisfying device or strong integrity levels. See 06 Configuration and tuning.

ADB connection

Symptoms: adb devices does not show a Waydroid device.

Solution:

# 方案 A：通过 Waydroid 内置 ADB（默认端口 5555）
# 先在 Android 中打开 ADB：
# "设置 → 关于平板电脑 → 连续点击"版本号"7 次启用开发者选项"
# "设置 → 系统 → 开发者选项 → 开启 USB 调试"

# 获取 Android IP 地址
sudo waydroid shell ip addr show
# 通常在 waydroid0 网桥上，如 <EXAMPLE_IP>

# 连接
adb connect <EXAMPLE_IP>:5555

# 方案 B：如果方案 A 失败，使用 waydroid 命令行操作替代 adb
waydroid app list          # adb shell pm list packages
waydroid app install foo.apk  # adb install
waydroid app launch com.example.app  # adb shell am start

GPU and display problems#

Screen flickering / tearing

Symptoms: the Android window flickers or shows horizontal tearing, especially while scrolling.

Root cause: GPU buffer scheduling is out of sync with the Wayland compositor's frame synchronization. This is common on older iGPUs or with particular Mesa versions.

Solution:

# 方案 A：强制软件渲染
# 当前官方文档未列出此 runtime 属性，改为 waydroid.cfg 的 [properties]：
# ro.hardware.gralloc=default
# ro.hardware.egl=swiftshader
# 应用启动期覆盖后再重启容器
sudo systemctl restart waydroid-container

# 方案 B：如果方案 A 性能太差，尝试调整 GPU 缓冲区
# 查看当前 GPU 渲染后端
waydroid log | grep -i "gpu\|egl\|render"

# 尝试切换到 SwiftShader（软件实现 Vulkan）
# 启动期属性：在 waydroid.cfg 的 [properties] 中设置 ro.hardware.egl=swiftshader
# 不猜测镜像中的 Vulkan HAL 名；检查实际可用 HAL
sudo systemctl restart waydroid-container

See 04 GPU and hardware acceleration for the full procedure for switching GPU backends.

Black / white screen (the application window does not render)

Symptoms: after Waydroid starts, its window is entirely black or white, but waydroid log shows no errors.

Root cause: the GPU compositor failed to initialize its rendering context.

Solution:

# 确认 GPU 检测情况
waydroid log | grep -i "gpu\|drm\|gbm"

# 手动测试软件渲染
# 当前官方文档未列出此 runtime 属性，改为 waydroid.cfg 的 [properties]：
# ro.hardware.gralloc=default
# ro.hardware.egl=swiftshader
# 应用启动期覆盖后再重启容器
sudo systemctl restart waydroid-container
waydroid session start

# 如果软件渲染正常 → 确认硬件渲染问题
# 查看 GPU 型号和驱动
lspci -k | grep -A3 -E "VGA|3D"
glxinfo | grep "OpenGL renderer"

Black screen on NVIDIA GPUs

Symptoms: on an NVIDIA GPU, Waydroid starts with an entirely black window and no rendered output.

Root cause: modern NVIDIA drivers support GBM, but the Waydroid image's gralloc/Mesa/EGL integration and upstream GPU selection may still not support this path.

Solution:

# 必须使用软件渲染
# 当前官方文档未列出此 runtime 属性，改为 waydroid.cfg 的 [properties]：
# ro.hardware.gralloc=default
# ro.hardware.egl=swiftshader
# 应用启动期覆盖后再重启容器

# 显式禁用 GBM
# 未确认此环境变量由当前版本读取，不使用它替代启动期 properties 配置
waydroid session start

# 永久设置（写入 ~/.bashrc 或 ~/.config/environment.d/waydroid.conf）
# 不写入未核实环境变量

# 或通过 waydroid prop 设置
# 启动期属性：在 waydroid.cfg 的 [properties] 中设置 ro.hardware.egl=swiftshader
# 不猜测镜像中的 Vulkan HAL 名；检查实际可用 HAL
sudo systemctl restart waydroid-container

Performance expectations for NVIDIA + Waydroid Waydroid with software rendering is unsuitable for any 3D applications or games. Even with Swiftshader (a CPU implementation of Vulkan), the performance gap must be measured for the actual application. NVIDIA users should set their Waydroid expectations at "barely usable 2D applications".

Intel + AMD hybrid graphics

Symptoms: on a dual-GPU laptop (Intel iGPU + AMD dGPU), the Waydroid window renders incorrectly or crashes.

Root cause: Waydroid may be using a different GPU from the Wayland compositor, causing a render-target mismatch.

Solution:

# 确认 Waydroid 渲染 GPU
waydroid log | grep -i "drm\|render"

# 确认 compositor 渲染 GPU
# Hyprland: hyprctl monitors
# Sway: swaymsg -t get_outputs

# 强制使用集成显卡（Intel）
# 在 waydroid.cfg 的 [waydroid] 中指定已核对的节点：
# drm_device=/dev/dri/renderD128

# 或强制使用独立显卡（AMD）
# # drm_device=/dev/dri/renderD129 # 按实际节点调整

DRI device numbering /dev/dri/renderD128 is usually the first GPU (iGPU), and /dev/dri/renderD129 the second (dGPU). Confirm with ls -la /dev/dri/render*.

Corrupted rendering in multi-window mode

Symptoms: after multi-window mode is enabled, resizing applications produces misaligned content or graphical corruption.

Root cause: Android 13's freeform window management is not yet fully mature, and some applications are not adapted to dynamic window-size changes.

Solution:

# 关闭多窗口模式
waydroid prop set persist.waydroid.multi_windows false
sudo systemctl restart waydroid-container

# 如果需要多窗口但部分应用有问题，仅为特定应用禁用：
# 在应用启动后不调整其窗口大小即可

See 06 Configuration and tuning for the full multi-window configuration.

Application compatibility#

ARM applications crash (x86 host)

Symptoms: an APK installs successfully but crashes immediately on opening, or displays "App has stopped".

Root cause: Waydroid defaults to an x86_64 Android image and cannot run ARM native libraries directly. An ARM translation layer is required.

Solution:

# Intel CPU → libhoudini（第三方部署的专有转译组件）
waydroid session stop
# 按已审阅的社区安装器和镜像版本选择 libhoudini，不假定有 waydroid-extras 命令

# AMD CPU → libndk（NDK 转译，兼容性更好）
# 或选择 libndk 组件，按同一镜像/应用对照测试，不由 CPU 品牌保证

# 重启 Waydroid
sudo systemctl restart waydroid-container
waydroid session start

# 验证 ARM 转译生效
sudo waydroid shell getprop ro.product.cpu.abilist
# 应包含 arm64-v8a 或 armeabi-v7a

Choosing between libhoudini and libndk

• libhoudini: a proprietary translation component commonly associated with Intel. The first choice on Intel platforms, but closed-source and updated irregularly.
• libndk: Android NDK-based ARM translation with better compatibility on AMD platforms. These translation components are usually proprietary binaries and are not the same as the open-source Android NDK compilation tools.
• The two are mutually exclusive and cannot be installed together.

See 06 Configuration and tuning for the full ARM translation configuration.

Play Store does not show certain applications

Symptoms: some applications do not appear in Play Store searches, or show "This app is not compatible with your device".

Root causes:

1. Not Play Protect certified (see the networking section above)
2. Waydroid's spoofed device model does not meet the application's requirements
3. Architecture incompatibility (x86 vs. ARM)

Solution:

# Step 1: Play Protect 认证（见上文"Play Store 无法连接"）

# Step 2: 检查镜像设备属性与应用过滤条件
# 原笔记的 persist.waydroid.device_name/manufacturer 未核实为官方接口
# prop set 成功不代表会更改 Android 设备型号；修改型号也不保证 Play 兼容性

# Step 3: 清除 Play Store 数据并重试
sudo waydroid shell pm clear com.android.vending # 会清除应用数据，先确认
waydroid app launch com.android.vending

# Step 4: 如果仍不显示，使用 Aurora Store 作为替代
# Aurora Store 不依赖 Play Protect 认证
waydroid app install com.aurora.store.apk

An application detects root / an emulator

Symptoms: an application displays "ROOT environment detected" or "Emulators are not supported" and refuses to start.

Root cause: Waydroid differs detectably from a physical device (ro.build.tags=test-keys, missing hardware fuses, and so on). Some applications use strict Play Integrity / SafetyNet checks.

Compatibility checks and historical approaches:

The following framework-based approaches are retained only as historical ideas from the source notes. Check version compatibility, security costs, and application service rules separately; success is not guaranteed:

# ro.* 通常在启动时只读，不能把启动后 setprop 当作可靠修改方式
# 镜像/启动配置的属性变化也不等同于设备完整性证明

# 中等方案：Magisk + LSPosed
# 1. 在 Waydroid 中安装 Magisk（需 root）
# 2. 安装 LSPosed 框架
# 3. 安装 Hide My Applist / Shamiko 模块
# 4. 对目标应用启用隐藏

# 但要认识到：

Play Integrity levels and application requirements Waydroid generally cannot satisfy strong integrity requirements that depend on trusted hardware (MEETS_STRONG_INTEGRITY). Self-certification and property changes do not automatically grant this level, because Waydroid has no TEE (Trusted Execution Environment) or secure hardware fuses. Applications differ in the integrity levels and server-side conditions they require, so do not assume that all such applications can never run; verify against current requirements. This is an architectural limitation, not a bug.

DRM applications cannot play video

Symptoms: Netflix, Disney+, Prime Video, and similar applications show a black screen or report "Device not supported".

Possible causes: unmet DRM requirements, such as Widevine levels, licenses, keys, or server-side device requirements. Software L3 differs from hardware-protected L1; it is incorrect to say that all DRM requires a TEE. Waydroid support should not be guaranteed.

Solution:

There is currently no available fix. The following workarounds are for reference only:

• Use alternative DRM-free video sources
• Watch the web version in a browser on the Linux host (Firefox/Chrome have better DRM support)
• Some L3 DRM content may work by modifying CDM files, but this raises copyright-compliance issues

An application requires a WiFi connection

Symptoms: some applications (such as Mihon and reading apps) cannot detect a WiFi connection and refuse to access the network.

Root cause: Waydroid uses a virtual Ethernet connection, which the application's WiFi-detection logic mistakes for no network.

Solution:

# 全局伪装 WiFi
waydroid prop set persist.waydroid.fake_wifi "*"
sudo systemctl restart waydroid-container

# 仅为特定应用伪装 WiFi（示例：Mihon 阅读器）
waydroid prop set persist.waydroid.fake_wifi "app.package.name"
sudo systemctl restart waydroid-container

# 查看当前 fake_wifi 设置
waydroid prop get persist.waydroid.fake_wifi

Touch / click input does not respond

Symptoms: clicking buttons inside an application has no effect, although scrolling and keyboard input work normally.

Root cause: some applications check for touch hardware, and Waydroid does not emulate a touch device by default.

Solution:

# 启用虚拟触控
waydroid prop set persist.waydroid.fake_touch "com.example.app"
sudo systemctl restart waydroid-container

# 如果仍不响应，尝试通过 scrcpy 作为控制器
# scrcpy 通过 ADB 提供更精确的触控模拟
scrcpy --serial=<EXAMPLE_IP>:5555

Game input problems

Symptoms: keyboard mappings in a game do not behave as expected, or multi-touch is required.

Solution:

# 方案 A：使用 scrcpy 替代 Waydroid 主窗口
# scrcpy 的触控模拟更精确，且支持键盘映射
adb connect <EXAMPLE_IP>:5555
scrcpy --serial=<EXAMPLE_IP>:5555 --turn-screen-off

# 方案 B：对于需要手柄的游戏
# scrcpy 支持 OTG / 游戏手柄直通
# scrcpy --otg 针对 USB OTG 场景，不适用于这里的网络 ADB 容器连接

# 方案 C：Key Mapper 应用
# 在 Waydroid 内安装 Key Mapper，自定义键盘到触控的映射

System-level problems#

Clipboard does not synchronize

Symptoms: copying and pasting between the host and Android does not work.

Root cause: Waydroid clipboard synchronization depends on the host's wl-clipboard tool.

Solution:

# 安装 wl-clipboard
# Arch
sudo pacman -S wl-clipboard

# Debian/Ubuntu
sudo apt install wl-clipboard

# NixOS（在 home.packages 或 environment.systemPackages 中）
# pkgs.wl-clipboard

# 安装后重启 Waydroid 会话
waydroid session stop
waydroid session start

# 验证剪贴板同步
echo "test from host" | wl-copy
# 在 Android 中应能粘贴

Clipboard limitations Waydroid synchronizes plain text only, not rich text, images, or files. For complex clipboard content, use adb push/pull as a supplementary approach.

System suspend / hibernation damages the container

Symptoms: after the system resumes from suspend/hibernation, the Waydroid container is unresponsive or its data is corrupted.

Root cause: filesystem state inside the Android container was not correctly frozen during suspension, which can cause inconsistencies after resume.

Solution:

# 挂起/休眠前手动停止 Waydroid（推荐设为 systemd hook）
waydroid session stop
sudo systemctl stop waydroid-container

# 然后执行系统挂起
systemctl suspend

# --- 或创建 systemd sleep hook ---
# 创建 /usr/lib/systemd/system-sleep/waydroid-sleep.sh

Create a suspend-hook script:

sudo tee /usr/lib/systemd/system-sleep/waydroid-sleep.sh << 'EOF'
#!/bin/sh
case "$1" in
  pre)
    # 挂起前停止 Waydroid
    # root sleep hook 没有用户 session bus，不在这里运行用户会话停止命令
    /usr/bin/systemctl stop waydroid-container 2>/dev/null
    ;;
  post)
    # 恢复后启动 Waydroid
    /usr/bin/systemctl start waydroid-container 2>/dev/null
    ;;
esac
EOF

sudo chmod +x /usr/lib/systemd/system-sleep/waydroid-sleep.sh

The session freezes after running for a long time

Symptoms: after Waydroid has run for several hours, its window freezes and Android applications stop responding.

Possible causes: OOM, a cgroup task limit, graphics/driver problems, or Android service failures. First check the actual pid_max and error logs. Do not assume it is 32768 or treat 65535 as a universal optimization.

Solution:

# 临时修改
sysctl kernel.pid_max # 先检查当前值，未证实耗尽不修改

# 永久设置
# NixOS 用 boot.kernel.sysctl 管理经过验证的值；不直接覆盖 /etc
sudo sysctl --system

# 验证
sysctl kernel.pid_max
# 输出当前实际值，没有统一要求设为 65535

Unable to stop the Waydroid container

Symptoms: waydroid session stop hangs or reports container is busy.

Root cause: a process inside Android holds an important lock or has not responded to SIGTERM.

Solution:

# 尝试 1：标准停止
waydroid session stop

# 尝试 2：强制停止容器
sudo waydroid container stop

# 尝试 3：直接使用 LXC 命令
sudo lxc-stop -n waydroid -k

# 尝试 4：终极方案 — 杀死所有相关进程
# 如需最后手段，先查清具体 PID，再定向终止；不使用广泛模式杀进程
pgrep -a -f "lxc.*waydroid" # 只查询；强杀可能丢失未写数据

# 确认无残留进程
pgrep -a -f waydroid

Insufficient disk space

Symptoms: waydroid init fails, or Android reports insufficient storage.

Root cause: Waydroid images and user data can occupy more than 5GB.

Investigating disk usage:

# 查看 Waydroid 磁盘占用
du -sh /var/lib/waydroid/
du -sh ~/.local/share/waydroid/

# 详细分层
du -h --max-depth=1 /var/lib/waydroid/ | sort -hr
du -h --max-depth=1 ~/.local/share/waydroid/ | sort -hr

# 典型占用：
# /var/lib/waydroid/images/system.img    ~1.2 GB
# /var/lib/waydroid/images/vendor.img    ~300 MB
# ~/.local/share/waydroid/data/data/     ~2-4 GB（用户数据 + 应用）

Cleanup approach:

# 清理应用缓存（在 Android 内）
sudo waydroid shell pm trim-caches 1G

# 或完全重建（会丢失所有数据）
sudo waydroid container stop
# 破坏性清理示例：先停止会话/容器、核对路径和备份，再手动决定
# sudo rm -rf -- /var/lib/waydroid
# 破坏性清理示例：先停止会话/容器、核对路径和备份，再手动决定
# rm -rf -- ~/.local/share/waydroid
sudo waydroid init -f # 强制初始化；先核对当前状态与备份

Audio problems

Symptoms: Android applications display video but produce no sound, or volume controls have no effect.

Solution:

# Step 1：确认 PulseAudio socket 连接
waydroid log | grep -i "audio\|pulse"

# Step 2：确认宿主音频正常
pactl info | grep "Server Name"

# Step 3：安装 Sound Quick Settings（通知栏音量控制）
# 从 F-Droid 或 APKMirror 获取 Sound Quick Settings APK
waydroid app install SoundQuickSettings.apk

# Step 4：或使用 ShizuTools 实现逐应用静音
waydroid app install ShizuTools.apk

Liquorix / Zen kernel incompatibility

Symptoms: the Waydroid container randomly crashes or becomes unresponsive, and dmesg contains PSI- or scheduler-related errors.

Possible causes: a specific compatibility problem with a particular kernel version, module, or image, requiring logs and a comparison kernel. Binder is not provided by PSI, and there is no evidence that all kernels of these types conflict.

Solution:

# 可用标准受支持内核做对照测试，保留备用引导，不视为唯一修复
# Arch:
sudo pacman -S linux linux-lts

# NixOS:
# 在 configuration.nix 中：
# boot.kernelPackages = pkgs.linuxPackages;
# 或
# boot.kernelPackages = pkgs.linuxPackages_latest;
# 然后 nixos-rebuild switch

# 如果必须使用 Liquorix/ Zen：
# 尝试关闭内核的 MuQSS/PDS 调度器（不同版本参数不同）
# 但不保证稳定，建议仅在测试环境中尝试

Quick diagnostic checklist#

When any Waydroid problem occurs, check the following in order:

# 1. 内核支持
ls -la /dev/binder*                # binder 设备
cat /proc/pressure/cpu 2>/dev/null # PSI 接口
cat /proc/sys/net/ipv6/conf/all/disable_ipv6  # IPv6

# 2. 服务状态
systemctl status waydroid-container
pgrep -a dnsmasq | grep waydroid

# 3. 网络链路
ip link show waydroid0
sudo nft list ruleset | grep waydroid 2>/dev/null || sudo iptables -L -v | grep waydroid

# 4. 容器日志
sudo cat /var/lib/waydroid/lxc/waydroid/waydroid.log 2>/dev/null
journalctl -u waydroid-container -b --no-pager -l -n 50

# 5. Waydroid 日志
waydroid log

# 6. 持久化属性
waydroid prop get persist.waydroid.multi_windows
waydroid prop get persist.waydroid.fake_wifi
waydroid prop get persist.waydroid.fake_touch

Organizing the output of the commands above helps quickly identify the specific layer responsible for common problems.

Summary#

Waydroid troubleshooting follows a clear path:

1. Kernel layer: Binder nodes/permissions → kernel and resource pressure → actual storage compatibility
2. Container layer: LXC version → systemd service → device permissions
3. Network layer: waydroid0 → dnsmasq → IPv6 → firewall FORWARD
4. GPU layer: GBM → render node → software-rendering fallback → special NVIDIA handling
5. Application layer: ARM translation → Play Protect → root detection → DRM limitations

Most problems can be located in the container startup failure and no network stages. At the GPU and application-compatibility layers, issues often involve limitations of Waydroid's architecture itself, so keep expectations realistic.

Verification sources#

Official Waydroid installation instructions.

Official Waydroid command documentation.

Waydroid upstream source.

Official Google self-certification procedure.

Official property documentation.

Google Play Integrity verdicts.