You are typing an email when the top bar vanishes
The desktop background turns solid gray. The mouse cursor stops responding to clicks. GNOME Shell has frozen, or it has crashed back to the login screen. You are not looking at a kernel panic. The system is still running. The display server just stopped drawing your interface. Switch to a virtual console with Ctrl+Alt+F3, log in, and run the recovery steps below. A botched recovery attempt can leave you unable to log in again. Run these commands from a TTY, not from a frozen desktop.
What is actually happening
GNOME Shell is not a background daemon that quietly manages windows. It is the main compositor and user interface process. It runs as a single thread for the UI, loads JavaScript extensions into its address space, and talks directly to the graphics driver. When an extension throws an unhandled JavaScript exception, the main loop blocks. When the GPU driver drops a frame buffer or fails to allocate VRAM, the compositor hangs. The result is the same. A frozen desktop or a sudden drop to the login prompt.
Fedora ships GNOME Shell with Wayland as the default display protocol. Wayland isolates applications better than X11, but it also means the shell process has stricter control over the screen. If the shell crashes, Wayland does not automatically restart it. You have to trigger the restart manually or reboot. X11 sessions behave differently. The X server can sometimes recover from a shell crash, but the window manager state is usually lost.
Extensions are the most common failure point. They run inside the same process as the shell. They share the same memory space. A memory leak in one extension will eventually starve the entire UI. A syntax error in a third-party script will halt the JavaScript event loop. The shell does not sandbox extensions by default. They have full access to the GTK and Clutter APIs. When they misuse those APIs, the whole desktop stops.
Config files in /etc/ are user modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The same rule applies to GNOME settings. System defaults live in /usr/lib/glib-2.0/schemas/. User overrides live in ~/.config/dconf/. Touching the wrong directory will break your next system update.
The fix
Start by checking what actually broke. Do not guess. The journal logs contain the exact JavaScript stack trace or driver error that caused the freeze.
journalctl -xeu gnome-shell.service
# -x adds explanatory text for common systemd errors
# -e jumps to the end of the log so you see the latest crash
# -u filters for the gnome-shell unit specifically
Look for lines containing JS ERROR, Extension caused an error, or MESA-LOADER. If you see a JavaScript stack trace, an extension is the culprit. If you see GPU memory allocation failures or DRM errors, the graphics stack is failing.
Disable all extensions immediately to isolate the problem. Moving the extension directory is safer than deleting it. You can restore it later if the issue was elsewhere.
mv ~/.local/share/gnome-shell/extensions ~/.local/share/gnome-shell/extensions.disabled
# Renames the directory so GNOME Shell cannot load any third-party code
# Keeps your downloaded extensions intact for later debugging
# Prevents accidental data loss from a rushed rm command
Restart the shell process. The method depends on your display server. Check which session you are running first.
echo $XDG_SESSION_TYPE
# Prints wayland or x11
# Determines which recovery command will work without breaking your session
# Wayland and X11 handle process termination differently
If you are on X11, send a SIGQUIT signal to the shell process. This triggers a clean restart without dropping your open windows.
killall -3 gnome-shell
# -3 sends SIGQUIT, which tells GNOME Shell to reload its UI
# Preserves running applications on X11 sessions
# Restores the top bar and overview in a few seconds
If you are on Wayland, the shell process is tied to the login session. You must terminate the session and log back in. This closes all applications.
loginctl terminate-session $(loginctl | grep $(whoami) | awk '{print $1}')
# Finds your active session ID and sends a termination signal
# Wayland requires a full session restart to reload the compositor
# Drops you back to the GDM login screen
Once the desktop returns, verify stability. Open a terminal and run a quick stress test on the UI. Open multiple windows, drag them around, and toggle the overview. If it stays responsive, re-enable extensions one at a time. Use the gnome-extensions CLI tool to manage them safely.
gnome-extensions enable <extension-id>
# Loads a single extension into the running shell
# Lets you test compatibility without touching the file system
# Fails gracefully if the extension is incompatible
Reboot before you debug. Half the time the symptom is gone after a clean session start.
Verify it worked
Confirm the shell is running without errors by checking the live journal output.
journalctl -fu gnome-shell.service
# -f follows the log in real time
# -u filters for the shell unit
# Watch for new JS ERROR lines while you move windows
If the log stays clean for ten minutes of normal use, the crash is resolved. If errors return, note the exact extension ID or driver message and proceed to the pitfalls section. Clear the GNOME cache if the UI feels sluggish after recovery.
rm -rf ~/.cache/gnome-shell
# Deletes compiled JavaScript caches and theme overrides
# Forces GNOME Shell to rebuild assets on next launch
# Fixes visual glitches caused by stale cached files
Run journalctl first. Read the actual error before guessing.
Common pitfalls and what the error looks like
Fedora updates GNOME Shell frequently. Extensions compiled or written for an older GNOME version will break when the JavaScript API changes. You will see this exact error in the journal:
JS ERROR: Extension <name>: TypeError: window._globalThis is not a function
The API changed. The extension needs an update. Disable it and wait for the maintainer to release a compatible version. Do not force it to run.
Proprietary NVIDIA drivers are another frequent cause. The nvidia package ships with its own kernel module and userspace libraries. When Fedora updates the kernel, the module rebuilds automatically. If the rebuild fails, the compositor loses hardware acceleration and falls back to software rendering. Software rendering on a modern desktop will freeze during window animations. Check the driver status with:
dnf module list nvidia
# Shows which NVIDIA module stream is active
# Confirms whether the package manager is tracking the driver correctly
# Reveals if multiple conflicting streams are enabled
If you see Error: Transaction test error during a system update, the package manager detected a conflict between the NVIDIA driver and the kernel headers. Run the update with the refresh flag to force a clean metadata pull.
sudo dnf upgrade --refresh
# --refresh forces dnf to download fresh repository metadata
# Prevents stale cache from blocking driver or kernel updates
# Resolves dependency resolution failures after partial upgrades
SELinux denials can also block extension files from loading. Fedora enables SELinux in enforcing mode by default. If an extension tries to read a file outside the allowed context, the shell process gets denied and may crash. Check for denials before disabling security policies.
journalctl -t setroubleshoot | tail -n 20
# Filters for SELinux alert messages
# Shows one-line summaries of blocked operations
# Points directly to the file path causing the denial
Trust the package manager. Manual file edits drift, snapshots stay.
When to use this vs alternatives
Use the killall -3 gnome-shell command when you are on an X11 session and need to reload the UI without closing applications. Use loginctl terminate-session when you are on Wayland and the compositor has completely locked up. Use gnome-extensions disable --all when you want a reversible way to test extension compatibility. Use sudo dnf upgrade --refresh when the crash started after a partial update or a kernel mismatch. Stay on the default Wayland session if you only deviate from the defaults occasionally. Switch to X11 only when you require legacy window manager features or specific proprietary driver workarounds.