Troubleshooting

Version: 0.15.2
Updated: June 2026

First Steps

Before debugging, check the boot log:

cat /boot/efi/EFI/LamBoot/reports/boot.log

The boot log records every phase with timestamps. During early boot (before the menu), it writes to the ESP in real time, so even if LamBoot crashes you will see how far it got.

For automated diagnostics, use lamboot-diagnose:

sudo lamboot-diagnose

Common Problems

LamBoot does not appear after reboot

Symptoms: System boots directly into GRUB, systemd-boot, or the OS.

Causes and fixes:

1. Not in boot order: Run efibootmgr to check. LamBoot should appear as a boot entry.

   sudo efibootmgr
   # Look for: Boot0002* LamBoot

   Fix: sudo lamboot-install --set-default to move LamBoot to first in the boot order.
2. Other bootloader is first: The UEFI boot order has another bootloader before LamBoot. Fix: Use efibootmgr -o to reorder, or lamboot-install --set-default.
3. Binary not on ESP: Verify the file exists:

   ls -la /boot/efi/EFI/LamBoot/lambootx64.efi

   Fix: Re-run lamboot-install.

Menu appears but no boot entries

Symptoms: LamBoot menu shows "No bootable entries found" or only system actions.

Causes:

1. No BLS entries on ESP: LamBoot reads \loader\entries\*.conf on the ESP only.

   ls /boot/efi/loader/entries/

   Fix: Run lamboot-install to generate BLS entries, or ensure your distro writes them to the ESP.
2. Filesystem driver missing: If /boot is on ext4 or btrfs and separate from the ESP, LamBoot reads those filesystems natively (it loads ext4, btrfs, and FAT directly, including on LVM, read in place), and a filesystem driver covers cases where native access is unavailable.

   ls /boot/efi/EFI/LamBoot/drivers/

   Fix: lamboot-install --with-drivers to install filesystem drivers.
3. Policy filtering: The allowlist or denylist in policy.toml may be hiding entries. Check the policy file.

Entry shows ! (warning) or X (error) indicator

Symptoms: An exclamation mark or X appears on the right side of a boot entry.

These are advisory only and never block booting. You can still select and boot the entry.

To see the specific message, select the entry and the footer shows the preflight detail.

Fix: Check that the kernel and initrd paths in the BLS entry point to files that exist on the ESP or an accessible volume.

Crash loop detected

Symptoms: Boot log shows "Crash loop detected", auto-boot may be disabled or a fallback entry is selected.

What happened: LamBoot incremented the crash counter on each boot attempt, and lamboot-mark-success.service never ran to clear it (because the OS never fully booted).

Fixes:

1. Select a known-good kernel: Use the menu to manually select an older kernel version.
2. Reset the counter: Boot into a working kernel, then:

   # The mark-success service resets it automatically
   sudo systemctl status lamboot-mark-success.service

3. Adjust the threshold: In policy.toml, increase crash_threshold:

   [security]
   crash_threshold = 5

4. After VM snapshot restore: The crash counter should auto-reset via vmgenid detection. If it does not, the vmgenid device may not be configured on the VM.

Black screen after selecting an entry

Symptoms: Screen goes black after choosing a boot entry. System may or may not be booting.

Causes:

1. Kernel is booting normally: Many Linux kernels clear the screen during early init. Wait 10 to 20 seconds for the OS to start, then try SSH.
2. Console driver state: LamBoot reconnects the UEFI GraphicsConsole driver before handing off. If this fails, text output may be invisible. The kernel should still boot correctly. Check via SSH or serial console.

Module appears to hang

Symptoms: After selecting a diagnostic module (diag-shell, pci-inventory), the "Booting: ..." screen stays and nothing happens.

Causes:

1. GraphicsConsole not reconnected: This was a known bug (fixed in v0.2.0). LamBoot's GUI opens the GOP protocol exclusively, which disconnects the UEFI text console driver. After the fix, connect_controller is called before starting any child image.
2. PCI scan on large bus: The PCI inventory scans all 256 PCI buses. On systems with many bridges, this can take several seconds. Wait for it to complete.

Auto-boot selects wrong entry

Symptoms: The auto-boot timer selects an entry you did not expect.

Fix: Set default_entry in policy.toml:

default_entry = "bls-fedora-6.19.9"

Without default_entry, LamBoot selects the first boot entry by sort order (highest version, per UAPI.10 sorting).

Recovery Procedures

F2: Firmware Setup

Press F2 from the LamBoot menu (or select "Firmware Setup" from the right column) to reboot into the UEFI setup. From there you can change the boot order, disable Secure Boot, or access the UEFI Shell.

F12: Cold Reboot

Press F12 for an immediate system reset.

Removing LamBoot from the Proxmox Host

If the VM is stuck in LamBoot and cannot boot:

# On the Proxmox host:
qm stop VMID
lvchange -ay pve/vm-VMID-disk-N
qemu-nbd --connect=/dev/nbd0 -f raw /dev/pve/vm-VMID-disk-N
mount /dev/nbd0p1 /tmp/esp

# Remove LamBoot
rm -rf /tmp/esp/EFI/LamBoot

# Or fix a specific file
# cp fixed-lambootx64.efi /tmp/esp/EFI/LamBoot/lambootx64.efi

umount /tmp/esp
qemu-nbd -d /dev/nbd0
qm start VMID

Resetting the Crash Counter

From inside the booted OS:

# The mark-success service handles this automatically
sudo systemctl start lamboot-mark-success.service

# Or manually delete the NVRAM variables
sudo efivar -d -n 4c414d42-4f4f-5400-0000-000000000001-LamBootCrashCount
sudo efivar -d -n 4c414d42-4f4f-5400-0000-000000000001-LamBootState

Booting with a Different Bootloader

If LamBoot is first in the boot order and you need to skip it:

1. Enter UEFI firmware setup (press the firmware's key during POST, usually Del, F2, or F10)
2. Change the boot order to put your other bootloader first
3. Or use the one-time boot menu (usually F8 or F11 during POST)

Boot Report Reference

boot.json Fields

boot.log Phases

Using lamboot-tools for Diagnostics

The lamboot-tools companion package provides automated diagnostic and repair tools:

See Also

• User Guide: getting started, daily use
• Configuration Guide: policy.toml reference
• Proxmox Guide: VM-specific deployment and monitoring
• LamBoot Tools: diagnostic and repair toolkit
• Security Guide: Secure Boot, TPM, crash loop details