Troubleshooting

Most problems here have a one-line fix. Find the symptom, then run what is under it. If a command below changes a file setup installed, see Updating for what that means for the next update.

Installing

setup says the plugins need a running Hyprland

The plugins are built against the compositor that is running, so setup skips them outside the session. Open a terminal inside Hyprland and run:

./setup plugins

hyprpm fails with “Failed to run a superuser cmd”

hyprpm keeps its plugins in a store that belongs to root, and asks for your password to write there. Run ./setup plugins from a terminal where sudo can ask.

The AUR packages were skipped

You declined to build an AUR helper, so only the pacman half was installed. Install yay or paru, or let setup build one, then run:

./setup packages

install skipped a program

install sets up Thunar, VSCodium, Vesktop and Spotify once, and skips one it cannot set up yet, with the reason: Thunar or Vesktop open, Spotify open or never started, no network. Close the program — for Spotify, open it once first and close it — then run:

./setup update

Each also has a verb of its own, such as ./setup vesktop, which stops with the reason instead of skipping.

A file ending in .new appeared

You edited a file setup installed, and the repository has a newer version of it. Yours is untouched; the repository’s is beside it. Compare the two, then keep one:

diff ~/.config/kitty/kitty.conf ~/.config/kitty/kitty.conf.new

Move the .new over yours to take the repository’s version, or delete the .new to keep yours.

The shell

The bar does not appear

The shell starts with the session. If it is not running, or it stopped, restart it with SUPER CTRL R. From a terminal, start it and read its log:

qs -d      # start the shell in the background
qs log     # print its log

The bar takes twice the space

Two shells are running, and each reserves room for its own bar. List them and stop the extra one by its process ID:

qs list
qs kill --pid <pid>

A change to the repository did nothing

The desk reads the copy in your home, not the repository. Copy it across:

./setup sync

Changes under system/ need ./setup system instead.

Night bay’s widgets are out of place

A desk installed before 0.2.1 keeps the shipped profiles as they first arrived, laid out for 18 columns, and a 1920 × 1200 screen holds 17: Night bay’s clock drops below the rest. Take the shipped file again from System → Profiles → Import…, which opens on the shipped profiles: pick 3-night-bay.json, switch to the new copy and delete the old one.

A control is dimmed, or missing

Most features depend on an optional package. A missing one takes its own control away: the control is dimmed, or left out entirely.

Missing	What goes
`hyprsunset`	The night light
`hyprpicker`	Picking a colour off the screen
`satty`	Annotating a capture
`tesseract`	Reading a region as text
`wf-recorder` and `wl-screenrec`	The recorder, from the bar
`pacman-contrib`	A live count of updates

Every package is in packages/pacman.txt and packages/aur.txt. See Packages.

Hyprland

Something in the Hyprland config does not apply

An error in one module does not stop the others, and hyprctl reload reports success anyway. Ask for the errors:

hyprctl configerrors

The config Hyprland reads is the copy in ~/.config/hypr/.

The glass or shake to find stopped working after a Hyprland update

Plugins are built against one version of Hyprland, and an update leaves them behind. Settings dims both switches until they are rebuilt:

hyprpm update
hyprpm reload

The pointer is blurry when it grows

The pointer is a small bitmap until the vector cursor has been built, which install does when it can reach the network. Run:

./setup cursors

An application that draws its own cursor, like an Electron window, still shows its own when magnified.

The power button does nothing

The shell handles the power button, so nothing happens while the shell is not running, or at the login screen. Some machines never report a short press at all. SUPER X and CTRL ALT Delete open the same session menu. Holding the button still forces a power-off.

install enables sddm only where no display manager is enabled, so a machine that already starts another one keeps it. Disable that one, then enable sddm:

sudo systemctl disable gdm      # or whichever one starts now
sudo systemctl enable sddm

With sddm running, a theme named in a file of /etc/sddm.conf.d/ that sorts after 10-impasto.conf, or in /etc/sddm.conf, wins over this one.

The theme does not load

SDDM falls back to its own theme and prints the reason in red on that screen, not in a terminal. Test the theme from the repository:

sddm-greeter-qt6 --test-mode --theme system/usr/share/sddm/themes/impasto

The restart and shut-down buttons are hidden in test mode. That is expected.

Another file in /etc/sddm.conf.d/ still sets InputMethod=qtvirtualkeyboard. Files there are read in name order, and a setting another theme left behind applies to this one too. Remove that line.

A file in /etc/sddm.conf.d/ that sorts after 10-impasto.conf sets its own GreeterEnvironment, replacing the one that lets the theme read the battery. Add QML_XHR_ALLOW_FILE_READ=1 to that line. The ring also stays empty if the battery is not BAT0, BAT1 or BAT2.

The terminal

fa greets with no picture

The greeting’s scenes are drawn with ImageMagick. Install imagemagick, then run ./setup sync, which draws them if they are missing. The next palette change redraws them too.

Other windows

Spotify keeps the old colours

The palette is written into the patched client and read when Spotify starts, so a Spotify that is open keeps the colours it started with. Restart it.

Spotify lost its colours after an update

A Spotify update replaces the files the palette was patched into. The next ./setup update patches it again, with the player closed, or do it now:

./setup spotify

It asks to make /opt/spotify writable when it is not.

VSCodium keeps the old colours

VSCodium never repaints a window that is already open. Run Developer: Reload Window from the command palette, or open a new window. ./setup vscodium selects the theme; without it, choose Impasto once from the colour theme picker (Ctrl K Ctrl T).

Vesktop is not themed

The theme is written, but Vesktop wears it only once it is ticked, and install ticks it only while Vesktop is closed. Close Vesktop and run:

./setup vesktop

Or tick impasto.css under Vesktop → Settings → Themes. After that it repaints while open.

GTK windows come up light

Whether GTK applications are dark is a machine setting, and it holds only when set from inside the session. From a terminal in Hyprland, run:

./setup defaults

Thunar’s folders stay blue

The folder colours are an icon theme, and dconf decides which one GTK uses. ./setup defaults sets it, or set it alone:

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

Papirus must be installed. Like every GTK colour, the change reaches the next window opened.

Qt windows are light grey

qt6ct is not installed, so the Qt half of the palette is never written. Install it, change the wallpaper or the palette once so the colours are written, and open the window again. KDE applications read kdeglobals instead, and get their colours either way.