It’s annoying. It’s been a bug for all too long. GNOME Shell Desktop irregularly hangs without a user-discernable cause or pattern. This isn’t minor trouble resolved with the Alt-F2 r (restart) command. Alt-F2 doesn’t respond. GNOME is hanged.

How do you know when it happens? Just look at the screen. Did you last lock it for security and now the desktop is right there for everyone to see? All separate desktops now hodge-podged into one?

You’ve got the GNOME hang.

GNOME will not respond. Got a terminal window open? Won’t work. Want to try Alt-F2? Won’t open.

System seems done with you.

Fix this now for the future. Set it up using this article. Next time GNOME Shell Desktop hangs you won’t need a reboot to recover. Don’t lose your desktop setup with a reboot. No need to restart all your work still in progress. This method resets after the problem without a reboot.

But only if you set up this method ahead of time.

Restarting GNOME Shell

Open a virtual terminal. Use Ctrl-Alt-F3. You get a login prompt in a virtual terminal named tty3.

Fedora 25 offers six virtual terminals. The system uses two: tty1 for your login screen and tty2 for your GNOME Shell Desktop. When GNOME is working, try it: Ctrl-Alt-F1 takes you to your login screen where your name appears as it did when you first logged in. Ctrl-Alt-F2 takes you back to your desktop. The rest are available any time, of which tty3 is the first available.

  • Use Ctrl-Alt-FnNum in a GNOME Shell screen.
  • Use Alt-FnNum in a tty screen.

When in the GNOME desktop, Ctrl-Alt is the function key prefix to get to another tty. Ctrl-Alt-F3 takes you to tty3, where the Ctrl-Alt prefix no longer switches. When you’re on a tty screen, Alt is the prefix. For instance, Alt-F4 — no Ctrl key — switches to tty4.

Look at the top lines of tty3. It shows the distro version and the kernel version on the top two lines. The full message uses the issue(5) file’s format:

$ cat /etc/issue
Kernel \r on an \m (\l)

In this /etc/issue file, escape codes refer to:

  1. The operating system identification (\S)
  2. The kernel release number (\r)
  3. The machine architecture (\m)
  4. The logical tty name (\l)

In your tty, login to get the traditional shell prompt.

Now it gets tricky.

The gnome-shell --replace command line option is supposed to restart GNOME shell. If it worked, you’d get back your desktop. If only. Typing it at the tty’s command line fails:

$ gnome-shell --replace
Window manager warning: Unsupported session type

Your tty session is not the GNOME shell session. This option tries to replace the running window manager, but it has to be executed within the running window manager (GNOME Shell Desktop) to get the job done. GNOME shell does not lookup the “currently running” session and act on it when you run this command outside of GNOME. Instead, GNOME Shell Desktop must itself replace its own running shell for you.

You can’t run a replace command within the GNOME Shell Desktop while it’s hanged so heavily that Alt-F2 won’t work. That’s what the r command does, but you can’t get there from here.

In that tty, launch your favorite text editor. Both vim, emacs, and other plain text editors will work. Attempts to use gvim will fail because the desktop manager isn’t running in the tty, but it will show you an error message and then launch vim.

Create a program file named ~/bin/gnome-shell-restart with the following contents:

# Trigger gnome-shell to restart when emergency file is removed. Fixes
# a freeze without losing files.

while true
  if [[ -f ~/delete-to-reload-gnome-shell ]]
    sleep 5
    touch ~/delete-to-reload-gnome-shell
    gnome-shell --replace

After saving the file, use chmod(1) to set the file’s execution mode.

The while true infinite loop keeps this program running so long as GNOME Shell Desktop is running. First thing the loop does is check if a file is in the home directory named delete-to-reload-gnome-shell.

There’s a descriptive name.

If that file exists, it sleeps for 5 seconds and checks again. If the file doesn’t exist, create it. Touch(1) makes an empty file. Then, run gnome-shell --replace and cycle back into the checking loop, which immediately sleeps for 5 seconds.

You can’t manually run this. It must run under the GNOME’s control.Create a desktop file named ~/.config/autostart/restart-gnome-shell.desktop with the following:

[Desktop Entry]
Name[en_US]=Restart GNOME Shell
Name=Restart GNOME Shell
Comment[en_US]=Restart GNOME Shell When Emergency File Missing
Comment=Restart GNOME Shell When Emergency File Missing

In the Exec line, replace /HOMEDIR with your full home directory pathname. That pathname stores in the $HOME variable. It is the value used by ~ in a pathname. Neither of those notations can appear in a Desktop file. Spell out the full pathname in the Exec line.

Putting this file in the ~/.config/autostart directory — it doesn’t need an execution mode — causes it to run when GNOME Shell Desktop starts running, when you login.

When you’ve set this the first time, log out of GNOME then log back in, or reboot if that’s more convenient.

Unhangifying GNOME

When you start GNOME normally, all desktop files in the subdirectory ~/.config/autostart launch whatever they specified. That restart loop runs throughout your GNOME session, but sleeps most of the time so it doesn’t interfere with your ongoing work.

When GNOME Shell Desktop hangs, you’ll know it because every desktop you’ve carefully setup now has its open windows all cluttered on one desktop, your GNOME panel is gone, and you can’t use Alt-F2.

Follow these steps:

  1. Use Ctrl-Alt-F3 to get to a virtual terminal, such as tty3.
  2. Login as yourself.
  3. When the $ shell prompt appears, type:
    • rm delete-to-reload-gnome-shell
  4. Logout of your virtual terminal.
  5. When the login prompt appears, use Alt-F2 to get back to the GNOME Shell Desktop.
  6. Wait less than 5 seconds.

The desktop will still be hanged. Less than 5 seconds after you removed the file, the desktop will redraw, all your apps will redistribute to the desktops they were originally on, and you’ll be back to normal.

Continue work as if nothing had gone wrong. I’ve noticed that after the redraw open GNOME terminal windows align a bit lower than they were before the hang. Some sort of positioning bug. Move them back up if it bothers you. This GNOME Shell Desktop hang bug has hit me about once every week or two. Let’s hope the GNOME developers find and fix this soon. Meanwhile, this technique works around it.

Leave a Comment