Troubleshooting

binfmt or QEMU failures

Run:

make check-host CFG=flashberry.local.yml

If handlers are missing or do not have the required fix-binary behavior, reinstall them on the host:

docker run --privileged --rm tonistiigi/binfmt --install all

Configuration rejected

Get the shortest feedback loop with:

python3 scripts/config.py validate flashberry.local.yml

Validation intentionally rejects malformed package names, unsafe hostnames, invalid SSH keys, malformed Wi-Fi settings, and unsupported image values before those values reach privileged shell operations.

Rootfs missing

If configure, shell, or image reports that the rootfs is absent, rerun the required preceding stage:

make rootfs CFG=flashberry.local.yml
make configure CFG=flashberry.local.yml

Image does not boot

Automated checks cannot prove firmware compatibility for every Raspberry Pi board revision. Confirm the generated boot partition contains firmware, kernel8.img, initrd.img, config.txt, and cmdline.txt, then perform the physical-board smoke test described in Releasing.

Emulation

QEMU's generic virt machine is not a Raspberry Pi firmware model. Emulation is useful for debugging userspace or architecture issues but does not replace a real boot test on the intended hardware.