Story / scenario
You reboot your Fedora machine after a routine update. The login screen appears. You type your password. Instead of your desktop, a solid purple screen fills the monitor with the text "Oh No! Something Has Gone Wrong." You click the button to restart, but the cycle repeats. You are locked out of your session. This happens most often after installing a new GNOME extension, updating the kernel, or switching between Wayland and X11 sessions.
What is actually happening
GNOME Shell is the component that draws the desktop, handles window management, and runs extensions. When Shell crashes or fails to start, the display manager falls back to this error screen. The purple screen is not a system crash. The kernel is running. Your files are safe. The graphical session simply could not initialize.
Think of GNOME Shell like the operating system for your desktop environment. If a plugin throws an exception that the shell cannot catch, the whole shell process exits. The display manager detects the exit and shows the error. The most common triggers are JavaScript errors in extensions, missing graphics drivers, or configuration files that reference removed packages.
GNOME Shell runs extensions in the same process as the core compositor. A badly written extension can crash the entire shell. Extensions also hook into the display server. If an extension tries to access a Wayland API that changed between updates, the shell may abort to prevent data corruption.
Run journalctl first. Read the actual error before guessing.
Recovery procedure
You need a terminal to fix this. Since the GUI is broken, you must use a virtual console.
Press Ctrl+Alt+F3. If you are on a laptop, you might need Ctrl+Alt+Fn+F3. The screen changes to a text login prompt.
Enter your username and password. The password will not show as you type. Press Enter.
# Switch to the third virtual console to get a text terminal.
# This bypasses the broken graphical session entirely.
# Press Ctrl+Alt+F2 or F1 to return to the display manager later.
Ctrl+Alt+F3
Once logged in, check the logs. GNOME Shell writes errors to the journal. The journalctl command lets you inspect these logs without a GUI.
# Check the last 50 lines of the gnome-shell log.
# The --no-pager flag prevents the output from freezing in less.
# This reveals JavaScript errors or driver failures that caused the crash.
journalctl -u gnome-shell --no-pager -n 50
Convention aside: journalctl -xe reads better than journalctl alone. The x flag adds explanatory text and the e flag jumps to the end. Most sysadmins type journalctl -xeu <unit> muscle-memory style. Use that pattern when you need more context.
Look for lines starting with JS ERROR or TypeError. These indicate an extension failure. Look for EE lines or failed to load module if the output mentions X11 or Wayland compositors. These indicate driver issues.
If you see a JavaScript error, it usually looks like this:
gnome-shell[1234]: JS ERROR: ... TypeError: Cannot read properties of undefined (reading 'iconName') ... at /home/user/.local/share/gnome-shell/extensions/bad-extension@foo.com/extension.js:42
Copy the extension ID from the path. That extension is the culprit. If you see driver errors, the graphics stack is the problem.
Fixing extensions
Extensions live in two places. User extensions are in ~/.local/share/gnome-shell/extensions. System extensions are in /usr/share/gnome-shell/extensions. User extensions override system ones. A corrupted user extension is the usual suspect.
Moving the user extensions directory disables them all. This is safe. GNOME will start without extensions. You can restore them later.
# Move the user extensions directory to a backup location.
# This disables all user-installed extensions immediately.
# GNOME will ignore missing extensions and start cleanly.
mv ~/.local/share/gnome-shell/extensions ~/.local/share/gnome-shell/extensions.bak
Restart the display manager to apply the change. The display manager manages login sessions. Restarting it kills the current session and brings up a fresh login screen.
# Restart the GDM service to reset the display manager.
# This terminates all active graphical sessions.
# Use sudo because GDM runs as a system service, not a user service.
sudo systemctl restart gdm
Switch back to the graphical session with Ctrl+Alt+F2 or Ctrl+Alt+F1. Log in. If the desktop appears, an extension caused the crash.
Re-enable extensions one by one to find the broken one. Use the gnome-extensions tool from the terminal.
# List all installed extensions with their IDs.
# The output shows the UUID and whether the extension is enabled.
# Use the UUID to enable or disable specific extensions.
gnome-extensions list
# Enable a specific extension by its UUID.
# Replace the UUID with the actual ID from the list command.
# Test the desktop after each enable to isolate the failure.
gnome-extensions enable <uuid>
Disable extensions before blaming the kernel.
Graphics drivers and NVIDIA
If extensions are not the cause, check the graphics stack. Fedora ships open-source drivers by default. If you use NVIDIA, you need the proprietary driver. Kernel updates can break the driver build process.
Convention aside: dnf upgrade --refresh is the normal weekly maintenance command. dnf system-upgrade is for crossing major Fedora releases. They are different commands. Don't conflate them. Run dnf upgrade --refresh to ensure all packages, including driver components, are up to date.
Check if the NVIDIA module is loaded.
# Check if the nvidia kernel module is currently loaded.
# If this returns nothing, the driver is not active.
# This often happens after a kernel update if the module build failed.
lsmod | grep nvidia
If the module is missing, reinstall the akmod-nvidia package. The akmod package builds kernel modules on boot. Reinstalling forces a rebuild.
# Reinstall the akmod-nvidia package to trigger a fresh module build.
# This fixes broken builds caused by interrupted updates or missing headers.
# The package manager will download the package and run the build script.
sudo dnf reinstall akmod-nvidia
After reinstalling, rebuild the initramfs. The initramfs contains the modules needed to mount the root filesystem and load drivers early in boot. If the initramfs is stale, the system may not load the new driver.
# Rebuild the initramfs to include the new kernel modules.
# This is required after kernel updates or driver reinstalls.
# The --force flag ensures the image is regenerated even if it exists.
sudo dracut --force
Reboot the system.
# Reboot to apply the new initramfs and load the rebuilt driver.
# This ensures the kernel picks up the fresh NVIDIA modules.
sudo reboot
Trust the package manager. Manual file edits drift, snapshots stay.
Verify it worked
After the reboot, log in normally. The desktop should appear without the purple screen.
If you fixed extensions, verify that the desktop is stable. Open a few windows. Check that the top bar renders correctly. If you re-enabled extensions, watch for crashes.
If you fixed drivers, check the GPU status.
# Verify the NVIDIA driver is loaded and active.
# The nvidia-smi command shows GPU utilization and driver version.
# This confirms the proprietary driver is functioning correctly.
nvidia-smi
If nvidia-smi works, the driver is good. If you see an error, the driver is still not loaded. Check journalctl -k for kernel messages related to nvidia.
Common pitfalls
Wayland and X11 behave differently. Some NVIDIA setups still prefer X11. If you are on Wayland and the desktop crashes, try switching to X11 at the login screen. Click the gear icon and select "GNOME on Xorg".
Extensions can conflict with each other. Two extensions trying to modify the same UI element can cause a crash. Disable all extensions, then enable them in small groups.
Configuration files in ~/.config/gnome-shell can also cause issues. If moving extensions does not help, rename the config directory.
# Rename the GNOME shell config directory to reset settings.
# This removes custom shell settings that might be corrupted.
# GNOME will recreate the directory with defaults on next login.
mv ~/.config/gnome-shell ~/.config/gnome-shell.bak
SELinux denials can block GNOME Shell from accessing resources. Check the SELinux log if you suspect a security policy issue.
# Check for SELinux denials related to gnome-shell.
# The setroubleshoot service summarizes denials in plain text.
# This helps identify if SELinux is blocking a required operation.
journalctl -t setroubleshoot -u gnome-shell
When to use this vs alternatives
Use the TTY recovery when the graphical session fails to start and you cannot access the desktop. Use journalctl -u gnome-shell when you need to identify the specific extension or component that caused the crash. Use mv on the extensions directory when you suspect a user extension is breaking the shell and want to isolate the issue quickly. Use sudo dnf reinstall akmod-nvidia when the kernel updated and the proprietary driver failed to build automatically. Use sudo dracut --force when the system cannot boot due to missing kernel modules in the initramfs. Use Wayland when you want hardware-accelerated compositing and modern input handling. Use X11 when you are running legacy applications or NVIDIA drivers that do not support Wayland fully.