Troubleshooting & FAQ
AI Translation Notice
This documentation page is an English summary synced from the canonical Chinese FAQ. See Chinese FAQ for complete details.
1. Why do extract or assemble reject my VDI snapshots?
- Cause:
images.pyenforces exact2465270784virtual bytes and matching SHA256s forbaseplusboot/system/vendor. Images from Android 12, other MuMu builds, previously modified systems, or running VMs fail immediately. - Action: Capture snapshots only from a completely stopped fingerprinted Android 15 x86_64 instance and retry using a fresh non-existent
--outputdirectory.
2. Why does build-native.py fail the 235-symbol gate (e.g., missing shmem_file_setup)?
- Cause: Missing UAPI headers during build can silently disable upstream pre-init features and alter exported/undefined symbol counts.
- Action: Supply clean ACK kernel archives and original config (
--kernel-archive,--kernel-config), and re-run from a fresh empty--outputdirectory without relaxing symbol gates.
3. Why does bind or install report unstable shutdown or built-in root enabled?
- Cause:
binding.pyandcontroller.pyqueryMuMuManager.exeto require built-in root off and three consecutive stopped observations before allowing exclusive disk writes. - Action: Power off the instance completely (disable background keep-alive and MuMu built-in root) and wait a few seconds before re-running.
4. How do I handle Windows CreateFileW / msvcrt.locking failures?
- Cause: Another emulator process, terminal holding the same
bindings/<name>.json, or antivirus/sync software holds an open handle tosystem-diff.vdior.state/. - Action: Exit all MuMu processes and close competing handles; never duplicate binding files to run parallel transactions on the same instance.
5. What happens if install fails mid-write vs external disk modification?
- Cause:
controller.pyisolates pre-write external changes (preserves external edits without blind rollback) from in-flight controller write failures (attempts atomic restoration inside the same exclusive handle, or stops safely on unknown partial states). - Action: Check
mumu-resukisu status, then runmumu-resukisu restore --transaction <TxId>. Never delete.state/files or edit digests manually.
6. Why did fetch-release download a new APK that still cannot build?
- Cause: Release retrieval (
releases.py) and offline registration (register-release.py) only collect verifiable metadata (catalogUpdated: false). They do not modifysupported-daemons.jsonor kernel patches until audited and tested on target. See Release Lifecycle & Compatibility.
7. Why are 29 tests skipped when running unittest on Linux?
- Cause:
tests/test_controller.pycontains 29 Windows Win32 exclusive-handle and locking fault-injection tests that run only on Windows; the remaining 48 tests execute on Linux.