How to recover a Debian server that won't boot after a kernel update while preserving Docker configs and containers

By Kevin Marcondes · Published on Oct 28, 2026 · 9 min read

Need to recover a Debian server that won’t boot after a kernel update while keeping Docker settings and containers intact? This practical guide shows how to restore boot using chroot, repair GRUB, rebuild initramfs and — if necessary — roll back the kernel without losing Docker volumes or configuration.

Signs of the problem and what’s at risk

Boot failures after a kernel update usually show as GRUB errors, an initramfs BusyBox prompt, or kernel panic. Before taking action, the goal is to restore the boot without losing data. Avoid reinstalling the system in haste — that can overwrite partitions and erase Docker volumes.

The safe strategy is to boot into rescue mode, mount the disk, chroot into the system, repair the bootloader and initramfs. Only after those steps should you decide about a kernel rollback.

• GRUB errors or returning to the boot menu
• BusyBox initramfs prompt asking for the root password
• Kernel panic messages when mounting root
• Boot loop after selecting a kernel
• Docker services unavailable, but data still present

What causes Debian not to boot after a kernel update?

The most common causes are misconfigured GRUB, initramfs missing storage or encryption drivers, and boot order changes introduced by virtualization. A new kernel can also be incompatible. The table below helps decide the corrective path.

How to mount the disk and chroot into the root partition

Chroot gives you the system environment to repair GRUB and initramfs. Boot into rescue mode or a Live ISO matching your architecture. If you use LUKS or LVM, you must unlock and activate volumes before mounting.

Identify partitions, unlock LUKS, activate LVM, mount the root and do bind mounts for /dev, /proc, /sys and /run. Then chroot into the system.

# Identifique dispositivos
lsblk -f

# Se houver LUKS
cryptsetup luksOpen /dev/sdXn cryptroot

# Ative LVM (se usar)
vgchange -ay

# Monte a raiz (ajuste o caminho do LV/partição)
mount /dev/mapper/vg0-root /mnt

# Monte /boot e /boot/efi se existirem
mount /dev/sdXn /mnt/boot
mount /dev/sdYn /mnt/boot/efi

# Bind mounts essenciais
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys
mount --bind /run /mnt/run

# Entre no sistema
chroot /mnt /bin/bash

Reinstall GRUB and rebuild initramfs

Repairing GRUB and initramfs solves most broken boots. Selecting the wrong disk in grub-install can overwrite another volume’s bootloader — confirm the destination before running it.

After reinstalling GRUB (BIOS or UEFI), update its configuration and regenerate initramfs so it includes the modules needed for the rootfs, LUKS and LVM.

# Dentro do chroot
# BIOS (Legacy): instale no disco (ex.: /dev/sda)
grub-install /dev/sda

# UEFI: instale apontando para a ESP (ajuste /boot/efi)
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=debian

# Recrie config do GRUB
update-grub

# Reconstrua initramfs (todos os kernels instalados)
update-initramfs -u -k all

How to safely roll back to the previous kernel

If the new kernel is the cause, switching back to the previous kernel is a straightforward rollback. In the chroot, list available versions and install the previous stable one. Then update GRUB and verify the boot entry on the next reboot.

Another option is to install a known stable kernel and hold the metapackage. That prevents unplanned updates until your next maintenance window.

# Dentro do chroot
apt-get update
apt-cache policy linux-image-amd64 | sed -n '1,10p'

# Instale uma versão anterior específica (ajuste o nome)
apt-get install linux-image-<versao-anterior>

# Atualize o GRUB
update-grub

# Opcional: segurar atualizações automáticas do kernel
apt-mark hold linux-image-amd64 linux-headers-amd64

Preserve Docker configurations and containers during recovery

Container data lives in Docker volumes under /var/lib/docker/volumes and in bind mounts. The daemon configuration is in /etc/docker/daemon.json and services may be defined as systemd unit files. Do not run apt purge docker without a prior backup.

If you need to reorganize storage, see how to move Docker volumes to another disk: move Docker volumes to another disk. Reinstalling the package usually keeps the data, but make a local backup to be safe.

• Critical directories: /var/lib/docker, /etc/docker, project/Compose directories
• Avoid tinkering with overlay2; prioritize copying volumes and bind mounts
• Ensure consistent UID/GID when migrating data to another host

# Ainda no chroot (ou no rescue montado em /mnt)
# Faça um backup rápido (compressão opcional) dos dados do Docker
cd /
tar -C / -cpf /root/backup-docker.tar \
  var/lib/docker \
  etc/docker 2>/root/backup-docker.log

# Exporte também diretórios de projetos (ajuste caminhos)
tar -C / -cpf /root/backup-compose.tar opt/projects srv/apps home/*/apps

If the system doesn't come back: how to rescue container data

If the system won't boot, you can still extract data by mounting the disk on another host or using rescue mode. Focus on /var/lib/docker/volumes and the bind mounts of critical services. To migrate quickly, follow the guide to migrate a Docker host to another VPS.

Avoid copying overlay2 layers. Recreate containers from the same images and reattach the copied volumes to your Compose files. Validate paths and permissions before bringing services back up.

• Avoid copying overlay2 layers; recreate containers from images
• Validate volume paths in docker-compose.yml before starting
• Perform sample checksums to validate integrity after copying

# No modo rescue (fora do chroot), copie os volumes para outro host
rsync -aHAX --numeric-ids /mnt/var/lib/docker/volumes/ \
  user@novo-host:/backup/volumes/

# No novo host, posicione os volumes e suba o Compose
# (ajuste docker-compose.yml para apontar os volumes corretos)

Post-recovery checklist and how to prevent future incidents

After restoring boot, stabilize the environment and reduce risks. Implement snapshots and backups with LVM snapshots + Restic to S3 (Debian). Strengthen practices from the VPS Linux Security Checklist.

Create maintenance windows for kernel updates: test a new kernel as secondary and promote it only after validation. Monitor host health, /boot space and GRUB/initramfs logs.

• Install a new kernel without making it the default; test then promote
• Create a snapshot/backup before kernel upgrades
• Review /etc/fstab for correct UUIDs and LUKS/LVM timeouts
• Monitor /boot space and initramfs/GRUB logs
• Document a kernel rollback runbook

# Exemplo: manter kernel antigo como padrão até validar o novo
grub-set-default 0  # Ajuste para a entrada validada
update-grub

Related reading on migration, volumes and backups

If you decide to migrate to another VPS or reorganize volumes after the incident, these guides help you do it safely with minimal downtime. Establish an off-host backup policy as well.

• Incremental encrypted S3 backups: Encrypted incremental S3 backups for Linux VPS

Frequently asked questions

What quick steps should I take when Debian won't boot after a kernel update?

Boot into rescue mode, mount the root partition, perform bind mounts and chroot. Reinstall GRUB, run update-grub and update-initramfs -u. If needed, install the previous kernel, update GRUB and test the boot entry before promoting it.

Does reinstalling Docker delete my containers and volumes?

Normal reinstall does not delete them; using purge that removes data will. /var/lib/docker generally retains volumes and layers. Back up /var/lib/docker and /etc/docker before taking action. Avoid altering overlay2 and prefer named volumes and bind mounts.

How do I know if I should roll back to the previous kernel?

If the system only boots with the old kernel or known regressions exist, rolling back is safest. Test via Advanced options in GRUB. If stable, set the old kernel as default and hold the metapackage until you investigate the root cause.

Can I copy the overlay2 directory to recover containers?

Not recommended. overlay2 contains internal layers that are not portable. Copy only application data from volumes and bind mounts. Recreate containers from the same images and reattach the volumes.

Is it mandatory to decrypt LUKS to repair the boot?

Yes — if root is on LUKS you must unlock it to mount and chroot. Use cryptsetup luksOpen, activate LVM if applicable, and mount partitions. Then run grub-install, update-grub and update-initramfs from within the chroot.

See also

• Intermittent 502 Bad Gateway in Docker Compose with Nginx & PHP‑FPM: how to diagnose and fix timeouts and connection overloads
• How to diagnose and capture packets for intermittent network issues between Docker containers on Debian
• How to detect and fix duplicate SKU inconsistencies between WooCommerce and your ERP without losing orders
• How to reduce build time and avoid duplicate artifacts in CI for large PHP monoliths