Repository navigation
Troubleshooting
The simple version: most problems end the same safe way: the device goes back to Android, and you try again. Below are the known problems, what causes them and what to do. If yours is not here, collect logs and open an issue.
- Wait two minutes after power-on; the first boot is slow.
- Use a good USB cable plugged straight into the computer.
- Make sure you use the right address:
192.168.77.1(F50) or192.168.78.1(U30 Air). - The USB serial console works even when networking does not:
screen /dev/cu.usbmodem* 115200on macOS. - After a fallback to Android, collect logs from a computer with
tools/collect-logs.sh.
Wait two minutes. If there is still nothing, unplug and replug it. Every boot that does not finish counts, and after 5
of them in a row (or the number you chose) the device starts Android. Then run tools/collect-logs.sh and open an
issue with the result.
About one boot in 20 on one board hangs in its first seconds, and the device then falls back to Android (this can take
around 20 minutes). Start Linux again with su -c mu300-linux or the Magisk module's Action button. If it keeps
happening, try 7.2 or 5.4: sudo mu300-update kernel 7.2.
FINDINGS 31m
With older boot images a single crash or reset of Linux sent the device back to Android. Start Linux again with
su -c mu300-linux, then update (see Updating). If Linux does not start any
more, run ./install.sh from a computer and choose update: it writes a fresh boot image and keeps your data.
macOS does not set up a network interface it has never seen while the screen is locked. Each device has its own USB
MAC address, so the first time one is plugged in (or after an update that brought new addresses) unlock the Mac and
the interface appears. With an F50 and a U30 Air plugged in together, they are 192.168.77.1 and 192.168.78.1; two of
the same kind need /etc/mu300/lan.conf to tell them apart.
Check that the SIM has a data plan, then run sudo mobile-data status. A missing plan looks like a connection that
keeps dropping. Leave the APN empty unless your carrier needs one (Mobile Data and APN).
Releases before v2026.10.13: the firewall's boot ruleset had no rules for the LAN, and on 5.4 the reload that should have
added them always failed. Fixed from v2026.10.13 on; update. On an affected release, log in over the USB
serial console (ttyGS0, a root shell) and run:
nft delete flowtable inet fw4 ft; fw4 reloadA read past the end of the internal storage never returned on devices whose partition table ends at the end of the disk
(the 32 GB variant, and an F50 with no gap behind userdata). Fixed from v2026.10.13 on. Reboot the device
to end the stuck reads, then install with the current installer (it updates itself from GitHub when it starts).
FINDINGS 38a
You probably have the 32 GB variant. Use an SD card (F50), or let the installer shrink userdata (experimental,
erases Android's data). See Installation. If the numbers look like neither a 64 GB nor
a 32 GB device, open an issue with the --check output.
Something has written into the unpartitioned area. Installing would overwrite it, and the installer makes you type
overwrite. If you are not sure what is there, stop and ask in an issue.
You do not need to log in to get out (unless Linux is locked):
- Back to Android: unplug the device about ten seconds after it powers on, then plug it in again, as many times in a row as your failed-boot count (5 by default). The device then falls back to Android.
-
Set a new password from your computer, without booting Linux:
It mounts the Linux filesystem from Android and rewrites the password, keeping all your data.
tools/reset-password.sh # ubuntu, openwrt or both - Start Linux again with
su -c mu300-linux(orboot/android-boot-linux.sh work/boot-linux-slotb.img), or reboot if Linux is the default.
Re-running ./install.sh and choosing update also keeps your data and sets the password you type.
- WPA3-only networks cannot be joined (the driver has no SAE). Switch the router to WPA2/WPA3 mixed mode.
- While the hotspot is on,
wifi-client connectsaves the network and asks for a reboot. See Wi-Fi Hotspot and Client.
On Ubuntu they are in journalctl -t kernel (warnings and errors only, from the start of each boot). Everything else is
in dmesg. Repeating vendor messages are filtered out by /etc/mu300/kmsg-ignore.
The device has no GPS; websites guess from the IP address, and mobile operators and VPN servers often look like another city.
GitHub's CDN throttles single connections in some regions. The installer already downloads in 8 parallel chunks; set
MU300_FETCH_JOBS to change that, or MU300_RELEASE_URL to use your own mirror.
Harmless when updating from v2026.10.14 or older: the older mu300-next-boot does not know --trial. The fallback to
Android still works.
The mainline kernels (6.18, 7.2) of v2026.10.11 and older leave charging off. Update (charging on mainline comes from v2026.10.12 on), or use kernel 5.4.
hostapd stops with start_dfs_cac() failed / AP-DISABLED (releases up to v2026.10.18). Those are DFS channels, and
the Wi-Fi driver cannot detect radar. Fixed from v2026.10.20 on: such a channel is replaced by 36 (or 149) with
a line in the log. On an older release choose 36-48 or 149-165, or auto on Ubuntu.
FINDINGS 42
On openwrt-luci up to v2026.10.18 one stuck AT command could blank every page, even the battery tile, for minutes,
also after a reboot. The panel's lock wait counted whole seconds instead of tenths (OpenWrt's sleep takes no
fractions), and some pages read the modem inside the request. Fixed from v2026.10.20 on; there the pages keep
their last readings and say how old they are. On an older release wait it out, or restart rpcd and mu300-atd.
FINDINGS 40
Up to v2026.10.20, on 5.4, when two network namespaces were alive at once and one went away (Docker containers, a
sandbox, unshare -n), the kernel could panic while cleaning it up (xfrm_sysctl_fini in the trace; issue #103); the
device restarts, and after a few of those it falls back to Android. Fixed from v2026.10.21 on; update. On an older
release keep to one container at a time, or use 6.18 or 7.2, which never had the bug.
FINDINGS 44
Up to v2026.10.20, rmmod sprd_wlan_combo on 6.18 or 7.2 panicked within a second (__run_timers: the driver left a
timer running in freed memory; issue #146). Fixed from v2026.10.21 on. On an older release do not unload the
module; restart the device instead. FINDINGS 45
Lines such as sc2355_dump_survey, idx 0, bssid not found, multicast? or data len is 251, skb need 576 at error
level, every six seconds or so in dmesg and logread (releases up to v2026.10.20). They describe the driver's
routine work, not faults (issue #140). From v2026.10.21 on they are debug lines, shown only when you ask for them:
echo 'module sprd_wlan_combo +p' > /sys/kernel/debug/dynamic_debug/control. The real errors next to them are still
logged.
The mainline kernels of v2026.10.19 and older took 500 mA from every port. From v2026.10.20 on they read the current the port offers (1.5 or 3 A) and charge at up to 2 A. On 5.4 the vendor stack decides.
A boot that started because a charger was plugged in stays a charging boot (LED blinking, hotspot and modem down) until you press the Wi-Fi key.
- No screen output over USB-C and no sound: the hardware path is not there (Hardware Notes).
- A load average around 12 on 5.4: vendor kernel threads waiting in D state are counted; the CPU is mostly idle.
- About 1.4 GB of RAM: the modem firmware reserves the rest.
- Never use OpenWrt's
sysupgradeor flash OpenWrt firmware images. - Never post your backup folder or logs containing your IMEI publicly.
MU300 Linux is an experimental hobby project with no warranty of any kind. Not endorsed by ZTE, Unisoc or any
operator. · Website · Source ·
Issues · This wiki is kept in the
wiki/ folder of the repository; corrections go there as pull requests.
Getting started
Using it
Keeping it running
Reference
Elsewhere