Documentation / Troubleshooting

Troubleshooting

This page covers common issues and how to resolve them. For general questions, see FAQ; for command syntax, see CLI Reference.

Installation Issues

“Permission denied” running `./install.sh`

Cause: Missing execute permission. Solution:

chmod +x install.sh

Package installation failures

Cause: A network issue, a package broken upstream, or a failed AUR build. Solution:

Read the installer’s one-line explanation and the end of install.log. An optional package that fails is skipped and listed at the end; a required one stops the install.
If a required official package is broken today, accept the installer’s offer to finish from the Arch Linux Archive snapshot of the last day the nightly install canary passed.
Check your internet connection.
Run ./install.sh --dry-run first to see the full resolved plan without installing anything.
On a terminal the installer offers a redacted failure report you can review and send as a GitHub issue.

You don’t need an AUR helper beforehand: the installer builds yay if neither yay nor paru is present.

Backup creation failures

Cause: Insufficient disk space, or a permissions issue on the backup directory. Solution:

Check available disk space in your home directory.
Make sure you have write permission to ~/.config-backup/ — this is where install.sh/uninstall.sh’s automatic snapshots live (see Installation for how this differs from the separate aphotic backup CLI).
Pass --no-backup to skip the snapshot entirely if you don’t need it for this run.

Theme Issues

Firefox not picking up the theme

Cause: Missing the Pywalfox extension. Solution: Install Pywalfox — Firefox theming depends on it and won’t apply without it.

Quickshell components not themed properly

Cause: wallust isn’t installed, or color generation failed. Solution:

aphotic theme list — confirms the CLI and theme data are readable.
aphotic theme set <theme-name> — try applying one explicitly.
Confirm wallust is installed and on PATH.

Theme cycling not working

Cause: State tracking or a configuration issue. Solution:

Confirm aphotic theme next/prev work from a terminal first, independent of the keybind.
Restart the shell daemon: SUPER+B (or systemctl --user restart aphotic-shell.service).

System Integration Issues

Keybindings not working

Cause: A syntax error in Hyprland’s Lua config, or a conflicting bind. Solution:

Check Configs/hypr/keybinds.lua (and your own ~/.config/hypr/custom.lua, which is never touched by the installer — see Contributing) for syntax errors.
Reload Hyprland’s config: hyprctl reload, or aphotic reload --full to reload both Hyprland and the Quickshell shell in one step (see CLI Reference).

Quickshell not launching properly

Cause: A missing dependency, an incomplete install, or a plugin that breaks startup. Solution:

Press Super+Shift+B (or run aphotic recovery present). It is a Hyprland bind, so it works when the shell doesn’t, and it shows what failed with the recovery options: disable the suspected plugin, safe mode, restore the last good state, or continue. aphotic recovery status prints the same diagnosis in a terminal.
aphotic safemode on holds every plugin back so the shell starts as core only; aphotic safemode off loads them again.

If recovery doesn’t help:

Confirm the packages your profile needs are actually installed (full pulls in more than minimal — see Profiles & Layers). aphotic sync --check lists any the installed release expects that are missing.
Confirm the shell’s QML is present at ~/.config/quickshell/aphotic/.
Restart the daemon: SUPER+B, or from a terminal: pkill -x qs && qs -c aphotic to see errors directly instead of relying on the systemd-supervised restart.

Wallpaper changes not applying

Cause: awww or wallust isn’t running correctly. Solution:

Confirm awww is installed and its daemon is running.
Confirm the active theme’s wallpaper directory actually has image files in it.
Try setting one explicitly: aphotic wallpaper -f <path>.

Performance Issues

Slow startup

Cause: A heavier profile/layer combination than your hardware needs. Solution:

Review your aphotic.toml — a minimal profile with only the layers you actually use starts faster than full with everything on.
Check for unrelated autostart programs slowing the session, not just Aphotic’s own pieces.

High CPU usage

Cause: A background service, or a specific Quickshell module doing more work than expected. Solution:

Use htop/btop to identify what’s actually using CPU — don’t assume it’s Quickshell without checking. aphotic perf snapshot records the shell’s and Hyprland’s cost, and aphotic runtime shows which shell surfaces are live.
If it is a Quickshell process, note which module and open an issue (see Support) with the details — this is the kind of thing that’s actionable to fix upstream, not something to work around blindly.

Diagnostic Commands

aphotic doctor              # dependency + config drift check
aphotic status              # profile, layers, plugins, services and version drift on one screen
aphotic recovery status     # why the shell failed to start, if it did
aphotic theme list           # confirm theme data is readable
./install.sh --dry-run       # see the full resolved plan, change nothing
aphotic ai status            # reachability check for Claude CLI / Ollama, if the ai layer is on
cat install.log              # the installer's own log, in the directory you ran install.sh from

Recovery

Restore your pre-install/pre-update configs

./uninstall.sh

Restores your most recent automatic snapshot from ~/.config-backup/ — see Installation.

Reinstall cleanly

Back up anything you want to keep manually first — your own ~/.config/hypr/custom.lua, any Configs/awww/<theme>/ art you added, etc.
Remove your local checkout: rm -rf Aphotic-Hypr
Clone again and run ./install.sh.

Reporting an Issue

When you open a GitHub Issue, include:

Your theme and profile/layers combination
Your GPU (NVIDIA specifics matter — several code paths branch on it)
The actual error output, not just “it doesn’t work”
Steps to reproduce

See Support for more on this.