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

The plugins were left for the first session

The plugins are built against the compositor that is running, so an install from a console leaves them to the first Hyprland session. That session opens a terminal on ./setup plugins, which asks for your password once; cancel it and the next login asks again. To build them now, from a terminal in Hyprland:

./setup plugins

hyprpm: command not found

hyprpm is a package of its own, not part of hyprland. Install it with the rest of the list, then build the plugins:

./setup packages
./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 Nautilus, VSCodium, Vesktop, Spotify, the camera and the boot splash once, and skips one it cannot set up yet, with the reason: 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.

update stopped: the pull left conflicts

You edited a file in the repository itself, and the release changed the same lines. The pull could not put your edits back, so update stopped before copying anything, and your edits are in the stash. Resolve the conflicts (git status lists them), then:

git stash drop
./setup update

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

Settings → System → Updates → Changed files lists it with Keep mine and Use the new one. Or by hand: move the .new over yours to take the repository’s version, or delete the .new to keep yours.

A file I deleted does not come back

That is on purpose: a file setup installed and you deleted stays deleted, so the wallpapers you removed do not return with the next update. Settings → System → Updates → Changed files has Restore, or from a terminal:

./setup sync --restore

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`	Recording
`pacman-contrib`	A live count of updates
`ddcutil`	The brightness of external monitors
`v4l-utils` and `howdy-next`	Face unlock

Every package but howdy-next, which ./setup face installs, is in packages/pacman.txt and packages/aur.txt. See Packages.

The brightness keys don’t dim a monitor

The keys act on the screen with the keyboard, and an external monitor is dimmed over DDC/CI with ddcutil. Check that ddcutil is installed (./setup packages), that DDC/CI is switched on in the monitor’s own menu, and that the monitor answers:

ddcutil detect

i2c-dev, which ddcutil needs, is loaded by ./setup system, or from the next boot. Most monitors behind a dock or an MST hub, and DisplayLink, are not reached, and NVIDIA’s proprietary driver needs its I2C option set. A screen that cannot be dimmed passes the keys to the first one that can.

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/.

Refraction 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.

The lock screen

Face unlock never starts

Settings → Session → Face unlock says what is missing and offers the step that fixes it, and Try it checks a face without locking. Face unlock needs an infrared camera, the lock’s PAM service and howdy-next with your face enrolled. ./setup system installs the service, /etc/pam.d/impasto-face; ./setup face installs howdy-next, points it at the camera and enrols you:

./setup system
./setup face

The lock never looks on its own: press a key or move the pointer. After three misses it looks again only when you press Enter in an empty field. The login screen always asks for the password.

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 boot splash does not show

./setup splash sets it up from inside the session and says why when it cannot: Plymouth not installed, an initramfs not built by mkinitcpio, or a boot loader it does not know, which gets no splash argument. Run it again and read its last line:

./setup splash

On a GRUB machine the argument comes from /etc/default/grub.d/impasto.cfg, which ./setup system installs; the verb rebuilds grub.cfg after it.

The camera

No call lists impasto camera

The virtual camera is listed only while the shell writes to it. Open the panel with SUPER SHIFT W and check that Virtual camera is on. If the panel says to run ./setup camera, run it; if v4l2loopback was already loaded with other options, the camera appears after a reboot.

The camera could not be opened

Another program holds the webcam itself. Close it, or pick impasto camera in it instead of the webcam.

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

Nautilus’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.