Server Not Booting or Stuck in Rescue Mode

A server that fails to boot can be caused by a corrupted filesystem, a bad kernel update, or a misconfigured /etc/fstab. This guide explains how to diagnose and recover.

Step 1 — Check the Server Console

1. Navigate to Servers → Your Server → Console.
2. Look for error messages during boot.

Common boot error messages:

Step 2 — Boot into Rescue Mode

If the server cannot boot normally, use LightYear's rescue mode:

1. Navigate to Servers → Your Server → Settings.
2. Click Boot into Rescue Mode.
3. Select a rescue OS (e.g., Ubuntu 22.04 Rescue).
4. Click Confirm.

The server boots into a minimal rescue environment with your disk mounted at /mnt.

Step 3 — Fix Filesystem Errors

In rescue mode, check and repair the filesystem:

$fsck -y /dev/vda1

fsck from util-linux 2.37.2
e2fsck 1.46.5 (30-Dec-2021)
/dev/vda1: recovering journal
/dev/vda1: clean, 123456/6553600 files, 2345678/26214400 blocks

If errors are found and fixed, reboot normally.

Step 4 — Fix a Bad /etc/fstab

A common cause of boot failure is a bad /etc/fstab entry (e.g., a block storage volume that is no longer attached).

In rescue mode:

$mount /dev/vda1 /mnt
$nano /mnt/etc/fstab

Comment out or remove any entries for volumes that are not attached:

# UUID=old-volume-uuid /mnt/data ext4 defaults 0 2

Step 5 — Reinstall the Bootloader

If GRUB is corrupted:

$mount /dev/vda1 /mnt
$mount --bind /dev /mnt/dev
$mount --bind /proc /mnt/proc
$mount --bind /sys /mnt/sys
$chroot /mnt
$grub-install /dev/vda
$update-grub
$exit
$umount -R /mnt
$reboot

Step 6 — Restore from Backup

If the server cannot be recovered, restore from a backup or snapshot:

1. Navigate to Servers → Your Server → Backups.
2. Select the most recent backup.
3. Click Restore.

[!TIP] Always take a snapshot before major system changes (kernel upgrades, package updates) to have a quick recovery option.