// internals

Debugging

boot.log first. It usually already knows.

boot.log

Visor writes \EFI\visor\boot.log on the ESP: every fallible step — config parse, detection decisions, PNG decode, file loads, device paths, LoadImage status codes, hand-off — gets one descriptive line. The log keeps the last 3 boots, so you can compare a failing boot against a good one. From Linux (ESP mounted at /boot):

cat /boot/EFI/visor/boot.log

Lines worth knowing:

Line	Meaning
`config: boot.conf not found, auto-detecting`	Running in zero-config mode.
`config: raw kernel scan found N`	How many vmlinuz+initrd pairs detection saw.
`config: cmdline taken from UKI .cmdline section` / `derived from fstab` / `from GPT root partition`	Which source produced the auto cmdline (and the exact line follows).
`hotplug: new filesystem volume detected / volume removed`	Live USB events.
`ERROR: LoadImage failed (status=0x...)`	The firmware refused the image — a following line says if Secure Boot rejected it.
`linux: StartImage() - handing control to kernel stub`	The last line of a successful boot.

The recovery console

If a boot returns (it never should), Visor drops into a recovery console instead of freezing: log pages the boot log on screen, reboot restarts, and you can go back to the menu. No serial cable required to see why a machine did not boot.

From Linux

Config validation: visor config validate --esp /boot checks boot.conf syntax from Linux before you reboot into a typo.
Install state: visor status reports binary versions, config presence, drivers, and encrypted artifacts on the ESP; visor doctor checks build/install dependencies.

Common failures

Symptom	Where to look
Entry missing from the menu	`boot.log` detection lines — wrong volume, gated scan, or unreadable filesystem (install a driver: `visor drivers`).
USB stick won't boot, "LoadImage failed"	Status code in the log. `0x1A`/security = Secure Boot rejected an unsigned loader — see Secure Boot.
Raw kernel lands in an emergency shell	No/wrong `root=` — check the derived-cmdline log lines, or set `cmdline=` explicitly.
LUKS still prompts twice	Password not enrolled as a LUKS key, or wrong `luks_preset` for your initramfs generator.
Menu is slow to appear	A filesystem driver connecting eagerly — check driver lines in the log; drivers should defer.