Products › lamboot-tools › Troubleshooting
Troubleshooting
Symptom-to-solution for common boot environment problems.
Start here: run a diagnostic
Before consulting the tables below, let lamboot-diagnose identify the issue. It checks every category and provides remediation commands for all findings.
bash
sudo lamboot-diagnose
# If the system won't boot: boot from a rescue medium with lamboot-tools installed,
# mount your root filesystem, then run with --offline /dev/sdX
BOOT FAILURES
System won't boot
| Symptom | Likely cause | First action |
|---|---|---|
UEFI shell drops to Shell> |
Missing or corrupted NVRAM boot entry | sudo lamboot-nvram list |
| GRUB error: file not found | GRUB binary missing from ESP or stale path in NVRAM | sudo lamboot-esp status |
Firmware loads fallback BOOTx64.EFI |
No valid NVRAM entries; firmware falling back | sudo lamboot-nvram list |
| Black screen after POST, no output | Bootloader binary missing or PE format mismatch | sudo lamboot-esp list |
| System boots to BIOS after UEFI migration | Migration was incomplete or NVRAM entries were cleared by firmware | Run lamboot-migrate status from rescue. Re-run lamboot-migrate to-uefi --stage nvram to resume. |
ESP ISSUES
EFI System Partition problems
| Symptom | Likely cause | Action |
|---|---|---|
| ESP full or almost full | Stale kernel images accumulated | sudo lamboot-esp clean --dry-run then sudo lamboot-esp clean |
| ESP is too small to expand | ESP is smaller than 512 MB; no room to resize | sudo lamboot-esp resize 512 (creates backup first, resizes partition) |
| ESP not mounted at boot | Missing or wrong /etc/fstab entry |
sudo lamboot-esp repair |
| ESP filesystem error on boot | Filesystem corruption on the FAT32 partition | Unmount ESP, then sudo fsck.vfat -n /dev/sdXN, then sudo lamboot-esp repair |
SECURE BOOT
Secure Boot failures
| Symptom | Likely cause | Action |
|---|---|---|
| Secure Boot violation at POST | Bootloader is not signed with an enrolled key | Disable Secure Boot in firmware, boot, then sudo lamboot-diagnose --category secureboot |
| MOK enrollment prompt on every boot | A kernel module or shim MOK is enrolled but not confirmed | sudo lamboot-signing-keys status. Follow enrollment prompts through MokManager. |
lamboot-signing-keys enroll fails: not in Setup Mode |
Secure Boot is not in UEFI Setup Mode | Clear the Platform Key (PK) in firmware settings to enter Setup Mode, then re-run. |
| UKI verification fails after signing | Wrong key used, or UKI was modified after signing | sudo lamboot-uki-build verify FILE then sudo lamboot-uki-build sign FILE to re-sign. |
TOOL ERRORS
Tool refused to run
| Exit code | Message pattern | Action |
|---|---|---|
| 4 (EXIT_UNSAFE) | Safety check refused: reason | Read the reason. Fix the underlying issue and retry. Or pass --force only if you understand the risk. |
| 7 (EXIT_PREREQUISITE) | Prerequisite not found: efibootmgr |
Install the named package. On Debian/Ubuntu: apt-get install efibootmgr. |
| 7 (EXIT_PREREQUISITE) | Root required for this operation | Re-run with sudo. |
| 6 (EXIT_NOT_APPLICABLE) | Operation not applicable: system is BIOS-only | The requested operation doesn't apply to this system. Not a failure. Skip in automation. |
| 1 (EXIT_ERROR) | Fatal error: detailed message | Read the message. If the state is inconsistent, lamboot-diagnose to assess, then lamboot-backup restore if needed. |
GETTING HELP
Collecting information for a bug report
Collect diagnostic info
# 1. Structured JSON report with all findings
sudo lamboot-diagnose --json > /tmp/lamboot-diag.json
# 2. Toolkit version info
lamboot-toolkit list --json > /tmp/lamboot-versions.json
# 3. Relevant system info
uname -a
efibootmgr -v
lsblk -f
Open an issue at github.com/lamco-admin/lamboot-tools and attach the JSON diagnostic output. Redact any information you want to keep private before sharing. The run_id field in the JSON correlates all log lines from the same invocation.