ArgoBox
ArgoBox Infrastructure & Automation
user@argobox:~/journal/2025-11-20-the-tty-that-saved-everything
$ cat entry.md

The TTY That Saved Everything

[Thursday, November 20, 2025] MOOD: TRIUMPHANT Gentoo
○ NOT REVIEWED

The TTY That Saved Everything

Date: November 20, 2025 Duration: Most of the day Messages: 322 Issue: Gentoo system wouldn’t boot to desktop Result: Full recovery via TTY

The Symptom

Power on. BIOS POST. Bootloader. Kernel messages scrolling.

Then: black screen with a blinking cursor.

No KDE Plasma. No SDDM login. No GUI at all. Just a cursor, blinking in the void.

The Panic (Brief)

My main workstation. All my work. Custom Gentoo installation I’d spent months perfecting.

And it wouldn’t boot.

The Recovery Path

Ctrl+Alt+F2

That’s the magic. Switch to TTY2. The graphical session is on TTY1 (or TTY7, depending on setup). Other TTYs are text consoles.

Gentoo Linux (tty2)

localhost login: _

The system was alive. Just the GUI was dead.

The Investigation

Logged in on TTY2. Started checking.

Check 1: What’s supposed to start the GUI?

rc-status
Runlevel: default
  display-manager     [ started ]
  ...

SDDM was “started” but clearly not working.

Check 2: SDDM Logs

cat /var/log/sddm.log
Failed to start X server

Not SDDM’s fault. X (or in my case, Wayland/KWin) wasn’t starting.

Check 3: Xorg Logs

cat /var/log/Xorg.0.log | grep EE
(EE) NVIDIA: Failed to initialize the NVIDIA kernel module

There it was. NVIDIA driver wasn’t loading.

The Root Cause

I’d updated the kernel the previous day. The NVIDIA driver was compiled against the old kernel. Module version mismatch.

uname -r
# 6.6.30-gentoo

ls /lib/modules/
# 6.6.28-gentoo  6.6.30-gentoo

ls /lib/modules/6.6.30-gentoo/video/
# (empty or missing nvidia.ko)

The NVIDIA module existed for the old kernel. Not for the new one.

The Fix

Still on TTY2:

Step 1: Rebuild NVIDIA Driver

emerge --oneshot nvidia-drivers

This recompiles the driver against the running kernel.

>>> Installing nvidia-drivers-545.29.06
>>> Compiling kernel module...
>>> Installing kernel module to /lib/modules/6.6.30-gentoo/

Step 2: Verify Module Exists

ls /lib/modules/$(uname -r)/video/
# nvidia.ko  nvidia-drm.ko  nvidia-modeset.ko  nvidia-uvm.ko

Modules present.

Step 3: Load the Module

modprobe nvidia

No error. Module loaded.

Step 4: Restart Display Manager

rc-service display-manager restart

Step 5: Switch to GUI TTY

Ctrl+Alt+F1

KDE Plasma login screen. Working.

What Went Wrong

Gentoo doesn’t automatically rebuild out-of-tree kernel modules when you update the kernel. That’s your job.

The proper update sequence:

# Update kernel
emerge gentoo-sources

# Configure and build
cd /usr/src/linux
make oldconfig
make -j$(nproc)
make modules_install
make install

# Rebuild dependent packages
emerge @module-rebuild  # <-- THIS IS THE KEY

# Reboot
reboot

The @module-rebuild set contains packages that install kernel modules: NVIDIA, ZFS, VirtualBox, etc. After a kernel update, run this or modules will be missing.

I’d forgotten. The system reminded me.

Why TTY Saved Everything

If I couldn’t get a shell, my options would have been:

  1. Boot from live USB
  2. Chroot into the system
  3. Fix from there (painful)

But TTY2 was right there. The kernel was fine. Userspace was fine. Only the GPU driver was broken.

Ctrl+Alt+F2 gave me a fully functional Gentoo system to work with. No live USB needed.

The 322 Messages

Not all for this issue. The session also covered:

  • Verifying the fix persisted after reboot
  • Setting up automatic module rebuilds
  • Understanding why emerge @module-rebuild exists
  • Checking for similar issues with other modules
  • Documenting the incident for next time

Each problem spawned three more questions. Classic troubleshooting.

Prevention

Added to my kernel update checklist:

#!/bin/bash
# kernel-update.sh

# 1. Build and install new kernel
eselect kernel set <new-version>
cd /usr/src/linux
make oldconfig
make -j$(nproc)
make modules_install
make install

# 2. Rebuild out-of-tree modules
emerge @module-rebuild

# 3. Update bootloader
grub-mkconfig -o /boot/grub/grub.cfg

# 4. Verify critical modules
ls /lib/modules/$(make kernelversion)/video/nvidia* || echo "WARNING: NVIDIA missing"

echo "Ready to reboot"

Now I can’t forget the module rebuild. The script does it for me.

The Lesson

TTY is always there. When the GUI dies, the text console is your escape hatch.

Kernel updates break modules. Every. Single. Time. Plan for it.

Gentoo makes you understand. On Ubuntu, this would “just work” (or fail silently). Gentoo made me learn exactly what broke and why.

When everything fails, Ctrl+Alt+F2 still works. That’s the power of a real Unix system.