When Linux won't boot: Diagnose, snapshot, fix, and verify with lamboot-tools

You updated a kernel or a bootloader, rebooted, and the machine didn't come back. Maybe it drops to a UEFI shell, maybe it sits on a black screen, maybe the firmware boot menu has nothing left to pick. When Linux won't boot like this, the boot chain broke somewhere between the firmware and the kernel, and the usual next move is to start guessing. This guide is the other option: Use lamboot-tools to find exactly what broke, snapshot the current state so the fix is reversible, repair it under a confirmation gate, and verify the result before you trust it. lamboot-tools is the Linux UEFI boot toolkit; if you're meeting it for the first time, the introduction covers what it is. Here we put it to work on a machine that won't boot.

You'll work from a live USB, because the broken machine can't start its own OS. Boot any Linux live image, install lamboot-tools from its GitHub release (or use a rescue image that already carries it), and open a terminal. From here it's one tool and one command at a time.

Look first, change nothing

The first rule of boot recovery: Don't fix what you haven't found. lamboot-diagnose reads the boot chain and reports. It changes nothing, so it's always safe to run first. Point it at the installed disk with --offline, and it reads the partition table, the ESP, and the boot configuration without booting the system:

$ sudo lamboot-diagnose --offline /dev/sda

partition_table:
  ✓ GPT, ESP present (type EF00)
esp:
  ✓ Mounted read-only, vfat, 71% free (364/512 MB)
  ⚠ Fallback loader EFI/BOOT/BOOTX64.EFI missing
      Firmware will not boot from removable media without an explicit NVRAM entry.
bootloader:
  ✗ No bootloader binaries found on ESP
      The ESP contains no recognized bootloader; this system will not boot.
kernel:
  ✓ 3 kernels found, all with matching initrds

Result: 1 critical, 0 error, 1 warning, 16 info

There's the answer in one screen. The update left the ESP with no bootloader binary, so the firmware has nothing to hand control to. No log archaeology, no guessing which low-level utility to reach for.

Read the finding

Every finding at warning severity or above carries a remediation, the exact command to fix it, not just a description of the problem. Ask for the machine-readable view to see what the scan wants you to run:

$ sudo lamboot-diagnose --offline /dev/sda --json \
    | jq '.findings[] | select(.severity=="critical") | {id, title, fix: .remediation.command}'

{
  "id": "bootloader.absent",
  "title": "No bootloader binaries found on ESP",
  "fix": "sudo lamboot-repair --offline /dev/sda"
}

The id is a stable identifier, the title is what a person reads, and remediation.command is the precise next step. You never translate a diagnosis into an action on your own; the tool already did it.

Snapshot before you touch anything

Before you change anything in the boot configuration, capture the current state, so whatever happens next you can put it back. lamboot-backup save records the NVRAM boot entries, the boot order, and the Secure Boot state:

$ sudo lamboot-backup save

ok: snapshot saved to /var/lib/lamboot/backups/2026-06-25T14-22-31-7f3a2c/
    NVRAM entries, boot order, and Secure Boot state captured

That's your safety net. If a repair makes things worse instead of better, lamboot-backup restore puts the boot configuration back exactly as it was.

Fix it, guided

Now run the command the scan handed you. lamboot-repair doesn't just act. It shows you the plan, waits for you to confirm, executes, and then verifies its own work:

$ sudo lamboot-repair --offline /dev/sda

Phase 1: diagnose
Phase 2: plan

Proposed repair plan (1 step):
  1. Install bootloader to ESP  [safe, reversible]

Execute: type 'yes' to proceed > yes

  ok: applied   Install bootloader to ESP
Phase 5: verify
  ok: all verify checks passed

Result: repaired (exit 0)

Nothing happened until you typed yes. That confirmation gate is the whole difference between a tool that acts on your boot configuration and one that asks first. The verify phase isn't decoration either: It re-runs the relevant checks after the change and tells you whether the fix actually held. If a step were risky, the plan would mark it, and lamboot-repair would refuse to run it without --force. The safe ones it just does.

Reboot, and confirm

Pull the live USB and reboot. The machine that wouldn't come up now does. For belt and suspenders, run the read-only scan once more on the live system and check that the count comes back clean:

$ sudo lamboot-diagnose
Result: 0 critical, 0 error, 0 warning, 19 info

That two-step loop, diagnose then repair, is the whole recovery. If a machine still limps up on its own, an old kernel, a fallback entry, you can skip the live USB entirely and let sudo lamboot-doctor run the same diagnose, plan, confirm, execute, verify sequence online in one command.

The same model, across the suite

What you just did isn't special to a missing bootloader. Every tool in the suite works the same way: Look first, snapshot, change only under confirmation, verify the result. The same structured output and the same reversibility cover the rest of the boot layer:

• ESP hygiene: lamboot-esp clean clears the stale loaders and orphaned kernel images that fill a small partition and wedge the next update.
• BIOS to UEFI: lamboot-migrate converts an install end to end, with rollback if anything goes wrong.
• Secure Boot: lamboot-signing-keys and lamboot-uki-build generate keys, enroll them through MOK, and sign Unified Kernel Images.

And because every tool emits the same JSON under one schema and returns the same exit codes, the whole thing automates. A script runs the scan, branches on the exit code (0 through 7: 0 is success, 2 is partial, 4 is refused by a safety check), and parses the findings:

$ sudo lamboot-diagnose --json | jq '.summary'

{
  "status": "pass",
  "findings_total": 19,
  "findings_by_severity": { "critical": 0, "error": 0, "warning": 0, "info": 19 }
}

On one machine or a hundred, the answer comes back the same.

What you can count on

Three things held the whole way through, and they're the point:

• You diagnosed before you changed anything. The first command was read-only and safe.
• You snapshotted first, so every change was reversible.
• The tool verified its own work and recorded what it did, so you always know what it found, how it checked it, and exactly what changed.

You don't need a broken machine to start. Run sudo lamboot-diagnose on a system you care about right now. It only reads, so it costs nothing but a few seconds, and you'll know your boot chain is sound well before the day it isn't.

lamboot-tools is free and open source, MIT or Apache-2.0, from Lamco Development LLC. Get it from GitHub Releases, or start with the product page.