Skip to content

Troubleshooting

David edited this page Nov 5, 2026 · 1 revision

The switcher or the overview does not open

Check that hyprglance is running and read its log. With the Home Manager module:

systemctl --user status hyprglance
journalctl --user -u hyprglance

If the service is inactive and Hyprland was not started through UWSM or with wayland.windowManager.hyprland.systemd.enable, graphical-session.target is never reached. Start hyprglance as in the manual setup instead.

If hyprglance is running, check that your Lua config calls setup():

hyprctl binds -j | jq '.[] | select(.key == "Tab")'

Hyprland's classic hyprland.conf is not supported.

A key does nothing or does something else

setup() binds Super + Tab, Super + Shift + Tab and F3. If your config binds them too, or binds a different key for the same purpose, change one of them. See Keybindings.

Number keys in the overview go to the wrong workspace

hyprglance cannot read where your own Super + N bindings go. Set overview.workspaceKeys to match them.

Config changes do not apply

  • If ~/.config/hyprglance/ did not exist when hyprglance started, restart it once.
  • If the file is not valid JSON, hyprglance keeps the last valid configuration and logs a warning.

Previews look grey

decoration:dim_inactive dims windows, and previews capture them that way. The overview turns it off while it is open, unless overview.undim is false. The switcher does not, because your windows would visibly change behind the strip.

hyprglance restarts on its own

A window closing by itself while the switcher or the overview is open can end the process with a Wayland error (invalid object). The Home Manager service restarts it, and it restores dim_inactive on start. With a manual setup, you have to start it again.