If The System Will Not Boot
Most boot failures after an update or a settings change can be repaired without reinstalling. Start with the older kernel in the boot menu; if nothing starts, repair the installed disk from the live ISO.
Installed systems · GRUB menu · Live ISO chroot
First: Which Screen Do You See?
| What you see | Go to |
|---|---|
A grub> prompt | The FAQ answer After installing Kodachi, my computer stops at a grub> prompt: two typed lines boot the system, and an update makes the fix permanent. |
Security Violation, PK unloaded or Setup Mode | The troubleshooting table of the Secure Boot guide. |
| The Kodachi boot menu, then a failure after you pick an entry (black screen, emergency mode, a BusyBox shell) | Boot an older kernel below, then repair from the live ISO if that does not work. |
| A disk passphrase prompt that refuses your passphrase | Check the keyboard layout and Caps Lock; a wrong passphrase gives you further tries. If a boot-time nuke password was entered, read this answer first. |
Boot An Older Kernel From The GRUB Menu
An installed Kodachi shows its boot menu for 10 seconds at every start. The last entry, Advanced options for Kodachi OS GNU/Linux, lists every kernel still installed, newest first, each with a normal entry and a (recovery mode) entry.
- Use the arrow keys to open Advanced options for Kodachi OS GNU/Linux.
- Pick the normal entry of the second kernel in the list, the one you ran before the last update. If only one kernel is listed, no older kernel is installed: go to repair from the live ISO.
- If Kodachi starts, the newer kernel or its boot image is the problem. Rebuild the boot images and the menu, then reboot into the default entry:
sudo update-initramfs -u -k all sudo update-grub - If the newer kernel still fails, keep using the older one and ask for help with the exact last lines on the screen. Do not remove the older kernel.
Recovery mode needs a root password
The (recovery mode) entries start a single-user root shell. Kodachi disables direct root login, so on most installs it answers that the root account is locked and cannot open a shell. Use the live ISO below instead.
Change one boot option for one start
Highlight an entry and press e to edit its kernel line for this start only, then Ctrl+X or F10 to boot it. Nothing is saved, so a mistake goes away at the next reboot.
Repair From The Live ISO
When no entry of the installed system starts, boot a Kodachi live USB of the same or a newer version, open a terminal and work on the installed disk from there. The live user kodachi has sudo without a password. Download and verify the ISO first if you do not have one (File Verification).
1. Find the installed system
lsblk -f
Look for your installed disk by its size. Its partitions show as one of these:
- Not encrypted: an
ext4partition holds the system, next to a smallvfatEFI partition. - Encrypted: a
crypto_LUKSpartition holds the system. An install from the text installer also has a separate/bootpartition and, inside the encrypted one, a volume group namedkodachi-vg.
In the commands below, replace /dev/sdX2 with your partition. On an NVMe disk the names look like /dev/nvme0n1p2.
2. Open and mount it
Not encrypted:
sudo mount /dev/sdX2 /mnt
Encrypted: the desktop installer names the opened volume luks- followed by the partition's UUID, so the commands read the UUID first. The second command asks for your disk passphrase.
U=$(sudo blkid -s UUID -o value /dev/sdX2)
sudo cryptsetup open /dev/sdX2 luks-$U
sudo mount /dev/mapper/luks-$U /mnt
If lsblk now shows LVM2_member under the opened volume (text installer installs), turn on the volume group and mount its root volume instead:
sudo vgchange -ay kodachi-vg
sudo mount /dev/kodachi-vg/root /mnt
If vgchange is not found, install it in the live session with sudo apt install lvm2 (needs a network connection).
Rebuilding the boot image on an encrypted system
Before step 4, check that you opened the volume under the name your installed system expects: sudo cat /mnt/etc/crypttab. The first word of the line is that name; on a desktop install it is luks- followed by the UUID, the name used above. If yours differs, run step 5 to undo everything, then open it again with that name in place of luks-$U. A boot image built under another name may not ask for your passphrase at the next start.
3. Enter the installed system
for d in dev proc sys run; do sudo mount --rbind /$d /mnt/$d; done
sudo chroot /mnt /bin/bash
mount -a
Your prompt is now inside the installed system as root. mount -a mounts its /boot and EFI partitions from its own /etc/fstab.
4. Repair
Run what fits your case. Each line is safe to run more than once.
| Case | Command |
|---|---|
| An update was interrupted or left packages half installed | dpkg --configure -a then apt -f install (the second needs a network connection) |
| The boot image is broken (BusyBox shell, missing root device) | update-initramfs -u -k all |
| The boot menu is wrong or missing an entry | update-grub |
A grub> prompt after the firmware lost Kodachi's boot entry | /usr/local/sbin/kodachi-efi-fallback-cfg (details) |
Do not reinstall the boot loader by hand
Do not run grub-install or install shim-signed or grub-efi-amd64-signed yourself. On an encrypted or Secure Boot install that can leave a system that stops at a grub> prompt. The Secure Boot guide has the supported repair for the signed boot chain.
5. Leave and reboot
exit
sudo umount -R /mnt
sudo vgchange -an kodachi-vg
sudo cryptsetup close luks-$U
sudo reboot
Skip the vgchange line when there is no volume group, and the cryptsetup line when the disk is not encrypted. Remove the USB stick and start the installed system.
Still Not Starting?
Write down or photograph the last lines on the screen and ask in the public Discord; the support page has the link. Say which installer you used (graphical or text), whether the disk is encrypted, and which of the steps above you ran.
Related Documentation
- Secure Boot Guide, the signed boot chain and module signing.
- Desktop Version Guide, installing and the boot menu.
- Known Limitations, what Kodachi does not cover.
- FAQ, the Installation and Troubleshooting answers.