// 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).
`tpm: TPM2 … banks=0x…` / `tpm: no EFI_TCG2_PROTOCOL`	Measured boot — whether the TPM was found and which PCR banks are active.
`tpm: locating EFI_TCG2_PROTOCOL` / `tpm: querying TCG2 capabilities`	Checkpoints around the two calls that can hang on an unusable firmware TPM. The last one printed names the call that did not return.
`tpm: last boot stopped inside the TPM probe` / `tpm: measured boot stays off`	The hang guard tripped. Clear the `VisorTpmStage` EFI variable to re-enable measured boot, or keep `tpm=0`.
`loader: Boot Loader Interface variables exported`	Systemd interop — `Loader*` vars published; look for `LoaderEntryOneShot` consumed lines.
`hotplug: new filesystem volume detected / volume removed`	Live USB events.
`clock: …` / `gui: screensaver dim→blank`	Live clock tick and idle state machine — useful when the clock or saver misbehaves.
`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.

Nothing on screen at all

If the machine shows no Visor output whatsoever, use the console checkpoints. Normal builds print Visor loading..., Visor: reading boot.conf, Visor: opening boot.log and Visor: log ready, reading the firmware clock as they pass each early step. The last line on screen names the step that died; no line at all means firmware never reached Visor.

Since 1.5.9 Visor does not write to the console at PE entry: that ConOut->OutputString call is the first privileged protocol call the image makes and can hang firmware before anything else runs. Diagnostic builds still carry the earlier EARLY_DIAG=1 print, which separates a firmware/PE-load failure from a relocation or console-setup failure.

The first boot.log write now happens before the first GetTime call, because EnhancedFatDxe stamps file timestamps with GetTime and a hang there can leave the file behind at 0 bytes. A failing log write, flush or rotation disables file logging for the rest of the boot and says so on the console, instead of retrying a wedged driver on every line.

What you see	Where the fault is
The diagnostic line, then a freeze before `Visor loading...`	After the image was entered but before Visor's C code runs — gnu-efi self-relocation or console setup. The firmware did hand over control.
`Visor loading...` or a later checkpoint, then a freeze	The named step is where execution stopped — for example reading the config, opening the log, or the firmware clock call. Get `boot.log` from a working boot if you can.
No checkpoint at all, with or without `EARLY_DIAG=1`	Before Visor got control: firmware POST, Secure Boot, or a bad `visor_*.efi` load. Check the firmware's own boot order and the file on the ESP.
`boot.log` is 0 bytes	The boot died before the first successful write (or inside `GetTime` while the file was being created); the console checkpoints still show how far it got.

Slow steps are timed and logged as boot.log lines, including Open calls that resolve the directory themselves and volume opens that a filesystem driver made. Those two are the metric that predicts a slow boot on a non-FAT driver — see Features → Non-FAT filesystems for the cache that reduces them.

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.