Troubleshooting by boot stage
What each stage prints when it stops, and what it means.
Find the last stage that spoke. A development build prints each stage’s lines on the screen and, with the USB link up, in the log. The way back from a setting that stops the phone is the safe boot (install guide); the way back from everything is in the install page.
1. Preloader and LK
Nothing of ours has run. If the phone reaches neither Android, the recovery nor fastboot, use MediaTek’s boot ROM mode with mtkclient and write your backup back. Never flash an LK you have not verified.
2. mtkloader
| What you see | What it means |
|---|---|
root: <partition>: HFS+ volume whole, the room after it; XNU | the root checks out: XNU starts (in the layouts that start XNU by default) |
root: <partition>: <reason>; Android | the volume’s headers are wrong, or the room after it is missing: Android starts. In the single layout Android then formats userdata: reflash the root |
root: ...; again, then ; stopped, and Root not read: hold Power on the screen | the root partition could not be read after three tries half a second apart: the loader stops rather than let Android format it. Power-cycle; try a safe boot |
safe boot: ... lines | the Volume Down window opened: the payload’s own line is used, with mp_bootrec=0 mp_mem4g=0 added and the GPU and radio arguments turned down; no room on the command line means the line was too long to add them |
ufs read: NO COMPLETION in 1 s | the UFS host did not answer the loader’s read; the slot is cleared and the list stopped |
3. The shim
The shim prints tagged lines: INITRD, PHYS, VIRT, ENTRY, MEM4G, SEGS, BOOTARG, JUMP, XNU, BOOTFILE.
| What you see | What it means |
|---|---|
no initrd in /chosen | LK’s tree has no ramdisk range: the boot image was not chained as the installer chains it |
no SWEETXNU payload, bad payload header | the ramdisk range does not hold the payload, or its header is not valid |
ramdisk overlaps kernel memory | the payload lies where the kernel goes |
MEM4G: no usable hole list: the 2 GB layout | the shim could not make a hole list (a hole below the kernel’s end, or over the shim itself): XNU runs in the 2 GB layout. See Memory map |
BOOTFILE: boot-args from userdata (VIVABOOT), none: boot-args from the payload, off (mp_bootrec=0), off (no mp_ufsroot=), or err=... lun=... | which command line the record gave: its own, the payload’s, off, or why it could not be read |
xnu returned | the kernel’s entry returned: it should not |
4. The kernel before the logo
| What you see | What it means |
|---|---|
panic mp_mem4g: all of DRAM and no hole list, mp_mem4g: N holes, mp_mem4g: hole ... | the shim’s hole list is missing, too long or not sorted and aligned |
panic mp_mem4g: the boot allocations ... ran into a hole | the first allocations lie in a hole |
| a hang before the Apple logo | find the last console line; the first things to check are the hole list (mp_mem4g=0 in a safe boot takes it out) and what the kernel maps before the logo |
| an unaligned data abort or a data abort in a reserved window or a flush | device-type memory or a by-physical-address flush on a hole; map it cacheable and flush through its mapping |
5. launchd
| What you see | What it means |
|---|---|
panic at launchd’s exec, EXEC_EXIT_REASON_WRONG_PLATFORM | an iOS binary on this kernel’s platform: the line needs unentitled_ios_sim_launch=1 ignition_level=1 launchd_unsecure_cache=1 |
mount of / fails with “Read-only file system” | the root is mounted read-only: mp_ufsrw=1 mp_rootrw=1 |
| a page “found” mapped when freed | something the loader mapped for itself (a firmware table) is in the free list |
6. SpringBoard and after
| What you see | What it means |
|---|---|
| black screen with the backlight on, or off | iOS set the backlight to 0 before its first real level; the first level is now ignored. Otherwise a GPU hang: restart, then a safe boot |
| the screen freezes after some use | a GPU hang (a job’s timeout is 3 s by default): kern.mapple_gpu_* and the link’s gpu command say what the driver saw; restart |
| touch stops, or phantom fingers | the touch chip lost its firmware or went quiet: the driver sends it again by default (mp_ili_quiet); a restart clears the rest |
| the phone reboots under load | the thermal hardware reset (armed by mp_therm_hwreset) or the watchdog: the reset reason is in Android’s log afterwards |
| Wi-Fi powers on and faults | the window’s address or its mapping: see Wi-Fi |
| Android’s kernel log shows an EMI MPU violation after a boot | something touched a reserved range: compare the hole list with the violation’s address |
Source: mtk/loader/mtkloader.c, shim/loader.c and shim/bootrec.c of mapple_loader at 415612e; osfmk/arm64/arm_vm_init.c of the kernel at dcb77a0; the bring-up’s run logs for what each stop turned out to be.
Applies to Release 1, development builds · Updated 15 November 2026