Fix common problems

Begin with the diagnosis

From your Pocket clone, run:

./diagnose

This checks dependencies, paths and services without changing them. Use the reported errors to decide what to investigate next.

The shell is missing or stuck

Check the service and its recent log:

systemctl --user status quickshell
journalctl --user -u quickshell -n 80 --no-pager

After addressing the reported error, restart the supervised process:

systemctl --user restart quickshell

Manage the existing service to avoid running a second copy of qs. If you only need to dismiss an open panel, press Escape.

A shortcut doesn’t do what this guide says

Open Super K. The desktop reads the current bindings, including local changes. If the shell itself is unavailable, look at ~/.config/hypr/hyprland.lua.

Pocket uses the Lua configuration format for Hyprland 0.56+. Check which file you’re editing: the compositor may no longer read an old hyprland.conf.

Colours don’t follow the wallpaper

Check whether pywal’s palette exists and is valid JSON:

jq '.special, .colors' ~/.cache/wal/colors.json

If that file is missing or unchanged after picking another image, investigate the wallpaper/pywal step first. If the shell recolours but one application doesn’t, look at that application’s integration. GTK, Qt and Spicetify each have their own part of the pipeline.

The team doesn’t show my activity

gh auth status

Sign in with gh auth login if necessary, then refresh the team. Missing artwork is a different issue: sprite assets are downloaded during the installer’s final phase and aren’t part of the Git clone.

Notifications or tray icons are missing

Quickshell owns the notification server. Another daemon, such as swaync, can compete for that D-Bus name. Run a single notification server; if you previously installed another one, check that it isn’t starting alongside Pocket.

Some applications register their tray icon only when they start. If icons disappear after a shell restart, restart the affected application. This isn’t normally needed after a fresh login.

A control is absent on this machine

Battery and internal backlight controls appear when the hardware supports them. Wi-Fi options require a Wi-Fi adapter; the Network panel remains available for wired connections.

For small text on a high resolution monitor, review display scaling. The shell also has fixed pixel sizes, so a different scale may need an appearance adjustment. See installation on other hardware.

Restore the home configuration

./install.sh restore restores the home files replaced by the configuration phase. It doesn’t remove packages or undo system-wide changes. The installation guide explains that boundary.