Support
Troubleshooting
Diagnose configuration, login, shell, wallpaper, theme, audio, capture and performance problems.
Start with the state of the session, then narrow down to the component that is misbehaving.
Collect the basics#
hyprctl version
hyprctl systeminfo
hyprctl monitors
hyprctl configerrors
journalctl --user -b -p warningKey log files:
| File | Contents |
|---|---|
/tmp/qs-bar-$USER.log | Quickshell stdout/stderr for the bar |
/tmp/walleclipse.log | WallEclipse daemon |
/tmp/walleclipse-daemon-out.log | Daemon output when started manually |
/tmp/screenrecord.log | screenrecord.sh decisions |
/tmp/screenrecord-gpu.log | gpu-screen-recorder output |
~/.cache/coloreclipse/colors.scss | Generated palette |
Configuration does not load#
luac -p ~/.config/hypr/hyprland.lua ~/.config/hypr/config/*.lua
hyprctl reload
hyprctl configerrors- Hyprland must include Lua configuration support. A build without it will
not read
hyprland.lua; this repository targets that configuration format. config/defaults/contains{{ PLACEHOLDER }}templates and is not valid Lua. Do not include it in a syntax check.- If a custom module broke the session, move
~/.config/hypr/config/custom/aside, reload, then re-add files one at a time. hyprctl reloaddoes not restart Quickshell; see the bar section below.
Bar is missing, blank or stale#
pgrep -a qs
tail -n 100 /tmp/qs-bar-$USER.log
lua ~/.config/hypr/config/scripts/bar.luabar.luastops the existing Quickshell process for~/.config/quickshell/archeclipseand starts a new one. If a lock is held, wait for it or remove the stale lock under${XDG_RUNTIME_DIR}after making sure no restart is running.- The bar window is full-monitor height with an input mask. If the pill is not
visible but
qsis running, check whether the bar was hidden withSUPER + ALT + Backspace. - After editing QML, a restart is required. A syntax error usually appears in the bar log and prevents the window from loading.
- Missing icons or fonts usually mean
ttf-jetbrains-mono-nerdornoto-fonts-emojiis not installed.
Greeter or login loop#
- Switch to VT2:
Ctrl + Alt + F2. - Log in and inspect:
systemctl status greetd
journalctl -u greetd -b- The installer backs up the previous greetd config to
/etc/greetd/config.toml.bak-noctaliaand enablesgetty@tty2.service. - Re-run the greeter component if the mirror is stale:
cd ~/ArchEclipse/.config/hypr/maintenance
python3 -c "from components import greeter; greeter.configure_greeter()"This asks for sudo, rewrites /etc/greetd/config.toml, installs the sync
sudoers rule and syncs the greeter mirror. It is the same function the
installer's greeter step calls.
Wallpaper does not change#
pgrep -a walleclipse
walleclipse current
walleclipse reload- Still wallpapers are drawn by WallEclipse; animated GIF/MP4/WebM need
mpvpaper. - Per-monitor state is in
~/.config/walleclipse/config/<monitor>/defaults.conf. Confirm the monitor name withhyprctl monitors -j. - If the picker is empty, check the file extensions and that files are under
~/.config/wallpapers. Restart the bar to rescan the folder cache. - If only the greeter wallpaper is wrong, re-apply the greeter target from the
picker; it requires
pkexec.
Colors are wrong or do not update#
coloreclipse get
coloreclipse apply
ls -l ~/.cache/coloreclipse/colors.scss- Settings → Theme → Dynamic Theme Colors must be on for wallpaper-driven regeneration.
colors.scssis generated; do not edit it.- If the shell has colors but Qt apps do not, verify
QT_QPA_PLATFORMTHEME=qt6ctand~/.config/qt6ct/colors/coloreclipse.conf. - If the shell has fallback colors, the palette file is missing or unreadable.
Brightness keys do nothing#
- Internal panels use
brightnessctl; external monitors use DDC/CI throughddcutil. - Both are in the package list. Confirm
brightnessctlworks directly and thatddcutil detectfinds the monitor. - The keybind tries the shell's
brightnessIPC first, then falls back toconfig/scripts/brightness.lua. If the shell is running but has no brightness backend, test the script manually:
lua ~/.config/hypr/config/scripts/brightness.lua -10- DDC/CI must be enabled in the monitor's OSD on some models.
No audio or volume keys do not work#
wpctl status
wpctl get-volume @DEFAULT_AUDIO_SINK@
systemctl --user status pipewire wireplumberUse pavucontrol to verify the default sink. Volume binds call
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+ and update the bar through IPC.
Screenshots fail#
grimis required for capture;slurpfor area selection;hyprpickerfor the freeze effect;wl-clipboardfor clipboard copy; ImageMagick for PNG optimization.- Read the settings the script uses:
jq '.screenshot' ~/.cache/quickshell/settings/settings.json- If area selection hangs, make sure the scripts are up to date. The tracked
scripts explicitly pass
</dev/nulltoslurpso a non-TTY caller cannot block it. Old copies of the script may still hang. - A cancelled area selection exits silently; that is expected.
Recording fails#
jq '.recording' ~/.cache/quickshell/settings/settings.json
tail -n 50 /tmp/screenrecord.log
tail -n 50 /tmp/screenrecord-gpu.loggpu-screen-recordermust be installed and able to capture the compositor.- Container/codec combinations are validated. WebM only accepts VP8/VP9/AV1; FLV only H.264. Choose MP4/MKV or a compatible codec.
- Frame-rate mode
contentis rejected on direct Wayland capture. - Only one recording session at a time is tracked through
/tmp/screenrecord.pid. If a previous recorder died, the script clears stale PIDs on the next run. - Output defaults to
~/Videos/ScreenRecords/.
Clipboard history is empty#
pgrep -a wl-pasteQuickshell's ClipboardService owns a single wl-paste --watch process and
culls stale watchers at startup. If you started additional watchers manually,
kill them and restart the bar. wl-clipboard must be installed.
Notifications#
Notifications are drawn by Quickshell. The installer removes dunst and
swaync because they would compete for the notification daemon slot. Check DND
in the shell settings and the notification history widget in the right panel.
Performance and stutter#
- Settings → Hyprland → Game Mode disables Hyprland animations, blur and shadows, zeroes gaps, enables tearing and requests a performance power profile.
- Lower blur size/passes before disabling everything.
- Settings → Animations controls the shell separately from Hyprland.
- Check
hyprctl monitorsfor the actual refresh rate.
Update problems#
archeclipseis a Zsh function. From Bash, run the updater directly:python3 ~/.config/hypr/maintenance/update.py.- The updater fetches the remote branch and hard-resets the checkout. Local
changes to tracked files are lost. Keep customizations in
custom/. - If the updater reports corrupt git history, it falls back to a fresh shallow
clone and copies it over
$HOME. - If a package manager was interrupted, the updater can kill
pacman,yayorparuand remove/var/lib/pacman/db.lck. Review what it is doing before confirming.
Displays and hotplug#
The base monitor module is a single fallback:
hl.monitor({
output = "",
mode = "highres",
position = "auto",
scale = 1,
})For a non-default layout, add a per-output rule above it in a custom module and
reload. nwg-displays is available from the Custom Scripts tab and writes to
~/.config/hypr/config/custom/monitors.conf; note that the tracked
configuration loads .lua modules, not .conf. Verify the generated file is
actually loaded before relying on it. TODO: document the supported
nwg-displays output path for the Lua configuration.
Input devices#
hyprctl devicesThe base config applies sensitivity = 0.1 to a device named elan-touchpad.
On other hardware that rule does nothing. Add your device by its exact name in a
custom module, or change the base device.lua.
Still stuck?#
Include the following in a GitHub issue or Discord question:
hyprctl versionandhyprctl systeminfo- the failing command and its output
- relevant log lines (
/tmp/qs-bar-$USER.log,journalctl, recorder logs) - the custom Lua/QML you added
Open an issue at github.com/AymanLyesri/ArchEclipse/issues.