Troubleshooting

Tip

On this page, press Ctrl+F to search or see the right sidebar to find your problem

Must read

Python virtual environment

The environment variable $ILLOGICAL_IMPULSE_VIRTUAL_ENV must be set properly, or some features of the Quickshell config will not work. In the provided default config, ~/.config/hypr/hyprland/env.conf, which is sourced by ~/.config/hypr/hyprland.conf, already contains this environment variable.

If somehow it isn’t there, add the following to your Hyprland config and restart it

env = ILLOGICAL_IMPULSE_VIRTUAL_ENV, $XDG_STATE_HOME/quickshell/.venv

You can run ./diagnose to recheck the value

Expected example

[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENV
declare -x ILLOGICAL_IMPULSE_VIRTUAL_ENV="/home/myself/.local/state/quickshell/.venv"
[---SUCCESS---]

Where myself represents the actual username.

Unexpected example 1

[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENV
./diagnose: line 30: declare: ILLOGICAL_IMPULSE_VIRTUAL_ENV: not found
[---EXIT 1---]

For the case above:

• It’s very likely that you’re still using old ~/.config/hypr/hyprland.conf, and forgot to replace its content with ~/.config/hypr/hyprland.conf.new. Just run cd ~/.config/hypr;mv hyprland.conf{,.old};mv hyprland.conf{.new,}.
• Ensure you have restarted Hyprland.

Unexpected example 2

[===diagnose===] declare -p ILLOGICAL_IMPULSE_VIRTUAL_ENV
declare -x ILLOGICAL_IMPULSE_VIRTUAL_ENV="\$XDG_STATE_HOME/quickshell/.venv"
[---SUCCESS---]

For the case above, the $XDG_STATE_HOME is not expanded, which seems really weird (maybe a Hyprland bug?).

• Make sure that when you run install.sh, you have not skipped and have properly executed the install-python-packages(), which should give you a non-empty ~/.local/state/quickshell/.venv.
• You may directly specify its value in ~/.config/hypr/custom/env.conf as:

env = ILLOGICAL_IMPULSE_VIRTUAL_ENV, /home/myself/.local/state/quickshell/.venv

And remember to replace myself with actual username.

Things to try at least once

• Restart Hyprland, or reboot your system, which is necessary for applying environment variable changes.
• Running install.sh again to ensure everything is installed properly. As the script is idempotent, you can run it as much as you like to check stuff or update the dotfiles

How to get logs

• If there’s a problem with something, open a terminal (Super+Enter) and run it. Look for errors/warnings that could be problematic.
• The bar and other shell elements are powered by Quickshell (ITS NOT WAYBAR 😭). If there’s something wrong with them, run the following in a terminal: pkill qs; qs.

Help

1. Search this page, then issues and discussions.
2. If you can’t find anything, open a new discussion.

While @end-4 is most active on Discord (@end_4), GitHub is preferred as @clsty has a better understanding of the install script and Arch Linux-related problems

Common issues

Themes don’t look right

Switch a wallpaper by pressing Super+Ctrl+T and choosing a picture in prompted window. If it doesn’t work, run ~/.config/quickshell/scripts/switchwall.sh in a terminal, follow the same procedure, see the logs and figure out the problem yourself or send it in an issue/discussion

Icon of some application missing in dock/overview

It’s technically not possible to have perfect icons. The icons are guessed from each app’s class, which is not necessarily the name of its icon.

Possible solutions:

GTK apps: Use gsettings to set icon theme

Maybe your app’s icon isn’t available in the default icon pack. In that case you can change it to another.

For example you can use Papirus. It is not used by default because of @end-4’s preference, but it has very good coverage of apps.

gsettings set org.gnome.desktop.interface icon-theme Papirus

Of course you must install it first, for Arch Linux use sudo pacman -S papirus-icon-theme.

Qt apps: Edit kde-material-you-colors config

Open ~/.config/kde-material-you-colors/config.conf Find these lines and edit to your liking

# ...
iconslight = breeze-plus
# ...
iconsdark = breeze-plus-dark

Music controls don’t show up

Reference: end-4/dots-hyprland#168 (Note: Old issue for AGS version)

• Make sure your player has Mpris support (here’s a list: MPRIS - Arch Wiki)
• If it’s a browser, install the Plasma Integration extension:
  • Firefox
  • Chromium

Make sure plasma-browser-integration package (for Arch, figure out the corresponding package yourself if not on Arch) is installed

Then, when firefox is playing media, the following command

dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames|grep mpris

the output should include

string "org.mpris.MediaPlayer2.plasma-browser-integration"

Only “plasma-browser-integration” names will work. others won’t.

If for some reason, firefox still does not have dbus org.mpris.MediaPlayer2.plasma-browser-integration showing up, consider the following steps:

1. Create a new profile using firefox --ProfileManager.
2. Launch firefox with the newprofile and install the Plasma Integration extension again.
3. Restart firefox with the new profile and try again.

• Note: playerctl -F metadata may also be helpful for debugging.

Weird icon names instead of icons show up

• Make sure the Material Symbols font (not Material Icons) is installed.
  • On Arch, use the ttf-material-symbols-variable-git package
  • If your distro does not have a package for it, install manually:
    • Download the .ttf files from Material Symbols’ repo
    • Put them in ~/.local/share/fonts
    • Refresh font cache with fc-cache -fv
    • Restart the shell with Ctrl+Super+R

loginctl lock-session does nothing

Reference: end-4/dots-hyprland#278

According to this post on Arch Linux Forums:

Something needs to listen to systemd-logind’s dbus signals for this to work.

Hypridle is capable to be this “thing”, which means you should ensure that it is running, and then loginctl lock-session will send signal to hypridle, as a result hypridle will lock the screen by executing the $lock_cmd defined in its config ~/.config/hypr/hypridle.conf.

See Hyprland Wiki for more.

Foot terminal: Why can’t I interrupt with Ctrl+C?

• In foot, Ctrl+C is configured to copy text. To interrupt, use Ctrl+Shift+C
• Don’t want this?
  • To remove this binding: in ~/.config/foot/foot.ini, comment or remove the line that says clipboard-copy=Control+c
  • Maybe if you use terminal apps a lot, it’d be a good idea to use a more feature-rich terminal