13 — Troubleshooting

Every procedure follows: symptom → likely cause → safe inspection → interpretation → least-invasive fix → verification → rollback.

Symptom index

Symptom	Start here
Nothing launches; sidebar or launcher is absent	Caelestia, sidebar, or launcher fails
A shortcut stopped working	Shortcut missing or conflicting
An application opens incorrectly	LibreWolf launcher fails, then Applications
Colours, icons, or sidebar styling disagree	Wrong colours, GTK/Thunar styling, or icons
Window or monitor behaviour changed	Display position or refresh rate is wrong and Windows
A user service failed	Inspect a failed user service
An update caused a regression	Hyprland config error or desktop fails after an update
Generated manual data looks old	Manual data appears outdated

Caelestia, sidebar, or launcher fails

Check caelestia --help, pgrep -a quickshell, and journalctl --user -b --no-pager | tail -200. No process suggests failed startup; a parser error should name a file and line. Fix only the reported fault, start the same ~/.local/bin/qs-caelestia command used by autostart, then restore the one changed file if verification fails.

Wrong colours, GTK/Thunar styling, or icons

Compare caelestia scheme get with the GTK theme and icon values from gsettings. A Caelestia glitch-lime scheme beside GTK adw-gtk3-dark is an expected toolkit boundary, not automatically a defect. Change one source with known precedence and retain its previous value for rollback.

Shortcut missing or conflicting

READ ONLYInspect runtime bindings

Copy

hyprctl binds -j | jq '.[] | {modmask,key,dispatcher,arg}'

Context: Requires an active Hyprland session and jq.

Expected: Active bind objects to compare with the generated table and source line, or an explicit socket/tool error.

Interpretation: Present at runtime but absent in the manual suggests stale generated data; present in source but absent at runtime suggests an include or parser problem.

Fix only a proven duplicate, rerun the inspection, and restore the removed line if behaviour regresses.

Display position or refresh rate is wrong

Compare hyprctl monitors -j with active monitor = lines. Transform changes effective geometry. Preserve the previous line, verify after reload, and roll back that line—not the complete configuration.

LibreWolf launcher fails

Check command -v librewolf and Exec= in the local desktop file. Do not inspect the browser profile. Test the executable directly and restore the desktop-file backup if needed.

Hyprland config error or desktop fails after an update

READ ONLYShow active configuration errors

Copy

hyprctl configerrors

Context: Requires a running Hyprland instance.

Expected: Empty output means the runtime parser reports no errors; text should identify a file or parsing problem.

Interpretation: No parser errors does not exclude application, service, driver, or package failures.

Preserve logs, compare the last change, and revert only the implicated line or package using the official Arch procedure. Do not delete the configuration tree.

Inspect a failed user service

Symptom: a shell component or helper that normally follows login is absent. Likely causes: the unit failed, its executable is unavailable, or its environment differs from an interactive terminal.

READ ONLYList failed user units

Copy

systemctl --user --failed --no-pager

Context: Run inside the affected user's session.

Expected: No failed units, or unit names to inspect individually.

Interpretation: A listed unit identifies a failed service boundary, not necessarily the root cause.

Inspect the named unit with systemctl --user status UNIT --no-pager and journalctl --user -b -u UNIT --no-pager. Replace UNIT only with the exact name returned by the first command. Fix the reported path, syntax, or dependency—not the entire service set. Verify the unit and its visible function. If a unit-file edit caused the regression, restore its timestamped backup.

Manual data appears outdated

Symptom: a binding or configuration fact disagrees with the current machine. First compare the generated record with its cited source file. Then inspect runtime state only when its socket is available. A difference between captured data and a later configuration is expected after an edit; it is not evidence that the parser is wrong.

Run pnpm update-manual from this project’s root only when you intend to refresh the stored audit and generated pages. The script is documented as read-only toward live configuration but writes project outputs. Review its diff, run pnpm check, then build. Roll back by restoring only the generated project files from version control or a project backup—never by changing live configuration to match stale documentation.

Verification discipline

• reproduce one symptom before changing anything;
• record the smallest piece of evidence that distinguishes likely causes;
• apply only the correction supported by that evidence;
• repeat the exact check and user action;
• retain a rollback copy until the next successful session.