# Post-mortem: an unformatted persistence file bricks the boot

*2026-03-17. Kept because the failure gives no useful signal about its own
cause, and it will happen again to whoever builds the next drive.*

## What happened

A freshly built bootable USB dropped straight into an initramfs prompt instead
of booting Ubuntu. Nothing on screen pointed at the real problem.

`persistence.dat` on the drive was a 20 GB **empty** file with no ext4
filesystem in it. `3-create-persistence.ps1` had found no standard WSL, taken
its fallback path, and produced a sparse file it never formatted. Ventoy read
`ventoy.json`, tried to mount that file, failed, and the boot collapsed into
initramfs.

The chain is silent at every step: the build script reports success, Ventoy
reports nothing, and initramfs says only that it has no root.

## The fix at the time

Formatted it using docker-desktop's WSL, which has `mkfs.ext4` even though it is
not a standard WSL distribution:

```bash
dd if=/dev/zero of=/tmp/persistence.dat bs=1M count=0 seek=20480
/sbin/mkfs.ext4 -F -L casper-rw /tmp/persistence.dat
```

Then copied it to `C:` and moved it onto the drive — docker-desktop's WSL cannot
reach other drive letters directly.

## How to tell a persistence file is real

Read two bytes at offset 1080. They should be `53 EF` — the little-endian form
of the ext4 magic number `0xEF53`. An empty file has zeros there.

This is the check worth keeping: it takes a second and distinguishes "built
correctly" from "built, and will fail at boot on someone else's desk".

## What changed in the scripts

- `3-create-persistence.ps1` now tries docker-desktop's WSL before giving up
- It verifies the ext4 magic number after formatting
- It only falls back to an unformatted sparse file when there is no WSL at all,
  and says so loudly — that path requires the user to run `mkfs.ext4` by hand on
  first boot, and then reboot

The user-facing version of this is in
[`bootable/README.md`](bootable/README.md) and
[`bootable/TROUBLESHOOTING.md`](bootable/TROUBLESHOOTING.md).