Troubleshooting

Start with the symptom. Keep the exact error and gnoblinctl version output when reporting a problem.

Gnoblin is missing from the login screen

Check that the gnoblin package is installed. On Fedora, run:

rpm -q gnoblin

For source builds, run make and then make install. It asks for sudo to copy the build to its prefix and add the login entry. See session registration.

The source build returns to the login screen

Log into another session or a text console and read the startup records:

cat "${XDG_STATE_HOME:-$HOME/.local/state}/gnoblin/session-last.log"
cat "${XDG_STATE_HOME:-$HOME/.local/state}/gnoblin/compositor-last.log"

The session record shows startup stages and process exit statuses. The compositor record contains its error output. Each file is limited to 64 KiB; the previous attempt is kept as session-previous.log and compositor-previous.log in the same folder.

Also check the session journal:

journalctl -b --no-pager -g gnoblin

If it reports a missing Gnoblin or Mutter library, run make and then make install to install the build. The PREFIX for make and make install must be the same.

Do not copy an executable out of build/ by hand. Its library paths point at the build directory and can fail under the login manager. Run make install instead. It checks that the installed executable loads its libraries without LD_LIBRARY_PATH set. Run it again after a rebuild or if the login entry changed.

The installed session does not need the source directory. If an earlier install left links in your home directory that point into it, run make install again to remove them.

GDM logs “Session never registered” when a session ends before it registers. Gnoblin's login entry sets X-GDM-SessionRegisters=false, so GDM's session wrapper registers the session itself about 10 seconds after it starts.

Check which case applies:

• The session ended within 10 seconds of starting. The warning is expected, and reinstalling does not prevent it.
• The session ran longer than 10 seconds. Check that the entry says X-GDM-SessionRegisters=false, and run make install again if it does not. If the message still appears, include the output of journalctl -b -u gdm in your bug report.

If no configuration exists, Gnoblin loads its built-in Lua configuration. Run gnoblinctl init to create an editable configuration tree from the copy embedded in the binary. The command leaves existing files unchanged.

Gnoblin starts with its embedded configuration before applying the user configuration. If Lua loading or native settings fail, it tries the last accepted settings, then keeps embedded defaults if those also fail.

The top-left ImGui recovery panel appears above application and shell layers and shows the error. Choose Open config to open its folder, fix the config in an editor, then choose Reload or run gnoblinctl reload from a terminal. Gnoblin keeps failed files unchanged. See configuration recovery.

The panel requires a running compositor. A missing library or a native compositor crash prevents it from displaying; inspect the login logs above for those failures.

The panel also reports config-owned autostart commands that cannot start or exit with an error. It names the failed component and its exit status or signal.

No bar, dock or launcher

Gnoblin does not include a desktop shell. Install one if you have not already.

Gnoblin reports failed config-owned autostart commands in its recovery panel. Choose Open config, Terminal, or Reload to investigate. Terminal is disabled when no supported terminal is installed. The panel hides while the session is locked. Choose Dismiss to hide the current notice; a new error opens it again.

If the panel does not appear, switch to another session or a text console and inspect Gnoblin's session logs for config-owned shell clients:

journalctl -b --no-pager | rg -i 'gnoblin'

A network needs a browser sign-in

Open the network's sign-in page in a browser. The NetworkManager secret agent handles Wi-Fi and VPN credential prompts.

A config edit does nothing

gnoblinctl config path
gnoblinctl config reload

Edit the printed path and read the reload error. Then check:

• Does this setting restart a child service, and does that affect its clients? See reload behavior.
• Did an unmatched include glob load nothing?
• Did a later list replace your rules or shortcuts?

My component's shortcuts or rules disappeared

Nonempty lists in gnoblin.configure replace earlier lists. Append to the existing list or edit its entries after the component loads.

A window rule does not match

Every matcher must match. Text matchers use case-sensitive Lua patterns, not JavaScript or PCRE regex. Check anchors, escaping (%. matches a literal dot), and the raw app ID. See window rules.

A shortcut fails

Run its command in a terminal. Check that the executable is on PATH. Command arguments do not expand ~, $HOME or pipes.

Check for another shortcut in your Gnoblin config that uses the same binding. Use gnoblin.configure.keybindings to change a built-in action. Set enable = false on a named gnoblin.configure.shortcuts entry to disable it. See shortcut conflicts.

Shell integration errors

Removing a setting does not reset it

Built-in bindings and native feature booleans persist in GSettings. Set the desired value explicitly. Removing an autostart entry does not stop its running process.

Blur is invisible

The application or panel must draw a translucent background. Rule opacity fades text too; it does not replace client background transparency. See blur.

There are two titlebars, or none

Check your frame mode. A renderer name alone does not enable SSD, and an unset protocol preference does not prove that the client draws a titlebar.

Gnoblin is slow or stutters after login

Check the scheduling policy of the compositor:

chrt -p "$(pgrep -x gnoblin | head -n 1)"

The policy should be SCHED_OTHER. A process tuner such as Ananicy can start Gnoblin as background work. The policy is then SCHED_IDLE, and the session misses its frame and input deadlines.

Ananicy-cpp rules

Install the gnoblin-ananicy-rules package from Gnoblin's package repository. It gives Gnoblin normal scheduling:

sudo dnf install gnoblin-ananicy-rules        # Fedora
sudo zypper install gnoblin-ananicy-rules     # openSUSE
sudo apt install gnoblin-ananicy-rules        # Debian
sudo pacman -S gnoblin-ananicy-rules          # Arch Linux

On another system, copy 99-gnoblin.types and 99-gnoblin.rules from the src/data/ananicy/ folder of the source to /etc/ananicy.d/. Then run sudo systemctl restart ananicy-cpp.

Log out and back in, then check the policy again. To go back to the daemon's defaults, remove the two files or the package.

The session ended and returned to the login screen

If the compositor stops on its own, every Wayland app stops with it, because apps cannot survive their compositor. GDM then shows the login screen. Gnoblin does not restart the compositor in place.

Log in again. If the compositor ended on a signal other than an orderly stop request, the recovery panel appears with the signal and the time the session ran, for example The compositor was stopped by signal 11 (Segmentation fault) after 53 seconds. The panel shows once. A clean logout never shows it.

The logs from the session that ended stay available until the next login after this one:

cat ~/.local/state/gnoblin/session-previous.log
tail -n 40 ~/.local/state/gnoblin/compositor-previous.log
coredumpctl list --no-pager | rg gnoblin

session-previous.log records the exit as compositor pid=... killed signal=11. Keep these files when you report the problem.

Portal requests fail or apps start slowly

Look for a portal backend that cannot start:

journalctl --user -b --no-pager | rg 'Failed at step EXEC'

A line such as xdg-desktop-portal-gnome.service: Failed at step EXEC spawning .../install/libexec/xdg-desktop-portal-gnome: No such file or directory means a user override points the service at a file that does not exist. Apps then wait for the failed backend whenever they read settings or open a dialog.

Show the unit with its overrides and note the path in ExecStart:

systemctl --user cat xdg-desktop-portal-gnome.service

A drop-in from a local build is the usual cause. Move it away and reload:

mv ~/.config/systemd/user/xdg-desktop-portal-gnome.service.d ~/xdg-desktop-portal-gnome.service.d.bak
systemctl --user daemon-reload
systemctl --user reset-failed xdg-desktop-portal-gnome.service

Restart the session so apps reconnect to the portal.

An X11 app has no title bar

Gnoblin draws the frame of an X11 app itself, as it does for a Wayland app. An X11 app that turns its decorations off gets no frame. A window rule can also change the frame of X11 apps: client_type = "x11" in a rule match selects them. Check your frame mode.

X11 apps closed but Wayland apps kept running

If Xwayland stops on its own, every X11 app closes. The compositor and the Wayland apps keep running. Start the X11 app again. Xwayland starts again when the first X11 app connects.

Xwayland does not run at login. pgrep -x Xwayland prints nothing until you start an X11 app. This is expected.

If the same X11 app closes each time, run it from a terminal and read its output. If Xwayland itself keeps stopping, report it with the compositor log:

tail -n 40 ~/.local/state/gnoblin/compositor-last.log

X11 apps look too large on a fractional-scale display

With a fractional display scale such as 1.25, Mutter rounds the X11 scale up to the next whole number. X11 apps then:

• report Xft.dpi: 192 instead of 96
• draw larger than Wayland apps at the same font size
• show small titlebar buttons

Check the value an X11 app sees:

xrdb -query | rg Xft.dpi

To draw X11 apps at their normal size, set the X11 scale to 1:

gnoblin.configure {
    xwayland = {scaling_factor = 1},
}

Reload the config. Xwayland does not restart, and X11 apps then report Xft.dpi: 96.

Use 0 to return to the automatic value. The accepted values are listed in the xwayland reference.

A window opens behind the focused window

A window from an app that is not the focused app can open behind the focused window.

With focus_new_windows = "prevent" set, the focused window stays in front and Mutter sets an attention flag on the new window. The flag does not produce a notification by itself.

The starter config raises modal dialogs, such as a portal prompt, with a gnoblin.window.created handler in config/10-windows.lua. If you replaced that file, add the handler back:

gnoblin.on("gnoblin.window.created", function(event)
    if event.window.modal then
        event.window:set_above(true)
    end
end)

Other windows from background apps stay behind the focused window. Check them with gnoblinctl window list --json; a hidden window has "focused": false.

Password dialogs from the keyring or GPG are the common case. With prevent they open on top but without focus, so typing does nothing until you click the dialog. Remove the prevent setting to use the default, allow, or show these prompts in your shell with the prompt broker.

The starter config uses allow, which lets an app take focus when it opens a window. A background app can then interrupt your typing. To keep focus where it is, set prevent:

gnoblin.configure {
    window_management = {focus_new_windows = "prevent"},
}

See focus options.

wl-copy does not return

With focus_new_windows = "prevent", wl-copy from wl-clipboard can block until you stop it. It opens a small window and waits for keyboard focus before it sets the clipboard, and prevent does not give that window focus. With allow it exits at once.

To use wl-copy, set focus_new_windows to allow.

An app cannot take a screenshot

Portal screenshots capture the entire desktop. Allow the request when asked. Interactive requests show a confirmation dialog with an Include pointer option, off by default. Cancel returns no image. Region selection, window selection and the portal's PickColor method are not available.

Capture fails while the session is locked or capture is inhibited. Unlock the session and try again. Check that PipeWire and the Gnoblin portal backend are running:

systemctl --user status pipewire xdg-desktop-portal-gnoblin

A log that mentions org.gnome.Shell.Screenshot means another portal backend is still running. Log out and back in to start the Gnoblin backend.

For a separate screenshot tool, use your shell's capture action or run:

grim ~/screenshot.png

The screen stays locked after the lock screen closes

If the lock client crashes or is killed, Gnoblin keeps the session locked. This is deliberate: the lock state becomes failsafe, and the screen and input stay locked until a lock client takes over and unlocks.

Check the state from another login, such as a text console or an SSH session:

export XDG_RUNTIME_DIR=/run/user/$(id -u)
gnoblinctl status

lock_state reads failsafe after a lock client failure.

Start your lock client again. It takes over the lock, and you can unlock it as usual. For example, with swaylock:

WAYLAND_DISPLAY=wayland-0 swaylock

Use the display name from the session, shown by ls $XDG_RUNTIME_DIR | rg wayland. After you unlock, lock_state reads unlocked.

Read the logs

journalctl -b --since '10 minutes ago' --no-pager | rg 'gnoblin-config|gnoblin-shader'

Restore a saved working config and reload to undo file changes. This does not undo launched processes or persistent GSettings values.