Skip to content

Boot Troubleshooting

Board does not boot after flashing

1. Check boot mode jumpers

The board must be set to the correct boot source after flashing. Jumper configuration differs between carrier boards — consult the Hardware Reference Manual of your specific board.

Common mistake: flashing eMMC while booted from SD card, then forgetting to switch the jumpers to eMMC boot mode.

2. Verify the flash completed correctly

If you used dd:

# Check exit code immediately after dd
echo $?   # must be 0
sync      # flush write buffers before removing media

If you used UUU, check the final output for errors — a successful flash ends with:

Done

3. Check power supply

An unstable power supply can cause silent write failures. Use the recommended supply voltage and current rating for your board (see Hardware Reference Manual).

U-Boot drops to interactive prompt

U-Boot could not find the kernel image or device tree. This is usually a misconfigured boot environment or wrong device node.

1. Inspect boot variables

At the U-Boot prompt:

printenv bootcmd
printenv bootargs

2. Identify the correct eMMC device

mmc list

This shows all MMC devices. Try booting from each:

setenv mmcdev 0
boot

setenv mmcdev 2
boot

3. Check that the boot partition is readable

mmc dev 2
mmc info
fatls mmc 2:1

You should see Image and the .dtb file. If the listing is empty, the boot partition was not written correctly.

4. Save a working environment

Once booted correctly, persist the fix:

saveenv
Kernel panic: cannot mount root filesystem

The kernel finds itself but cannot mount rootfs. The most common causes are a wrong root= device or a missing filesystem driver.

1. Find the correct device

Boot from SD card and run:

lsblk -o NAME,SIZE,TYPE,TRAN

eMMC is typically the device with TRAN=mmc. Note the device name (e.g. mmcblk2) and the rootfs partition number.

2. Check current bootargs

At the U-Boot prompt:

printenv bootargs

Locate the root= parameter. If it reads root=/dev/mmcblk0p2 but eMMC is mmcblk2, fix it:

setenv bootargs console=ttymxc1,115200 root=/dev/mmcblk2p2 rootwait rw
boot

3. Persist the fix

saveenv
Board stuck at SPL / no U-Boot output

SPL (Secondary Program Loader) initialises DDR before handing off to U-Boot. If SPL hangs silently, the likely cause is a DDR configuration mismatch.

  • Make sure the imx-boot binary matches the DDR size of your module. Check DDR Selection.
  • Re-flash with the correct imx-boot binary for your hardware variant.
  • If using UUU, verify you passed the right boot file as the first argument:
sudo uuu -b emmc_all imx-boot-<machine>.bin <image>.wic.zst