Skip to main content

​
Installation Problems

This occurs when files already exist at the target location.Solution:
# Backup existing configurations
mv ~/.config/hypr ~/.config/hypr.backup
mv ~/.config/waybar ~/.config/waybar.backup
# etc.

# Then run stow again
cd ~/dotfiles
stow -v -R -t ~/.config config
Alternative approach:
# Force stow to adopt existing files
cd ~/dotfiles
stow --adopt -t ~/.config config

# This moves existing files into your dotfiles repo
# Review changes with:
git diff

# If you don't want those changes:
git restore .
The install script only creates symlinks, it doesn’t install packages.Solution:Install required packages manually:
# Core Hyprland components
sudo pacman -S hyprland hyprpaper hypridle hyprlock

# Status bar and notifications
sudo pacman -S waybar swaync

# Terminal and launcher
sudo pacman -S ghostty wofi

# System utilities
sudo pacman -S brightnessctl wpctl playerctl

# Clipboard and screenshots
yay -S cliphist hyprshot

# Shell and tools
sudo pacman -S zsh btop cava fastfetch

# Editors
sudo pacman -S neovim
yay -S vscodium-bin
Check the main README or documentation for a complete dependency list.
You’re missing Nerd Fonts which provide icons and glyphs.Solution:
# Install JetBrains Mono Nerd Font
yay -S ttf-jetbrains-mono-nerd

# Or install all Nerd Fonts
yay -S nerd-fonts-complete

# Update font cache
fc-cache -fv

# Logout and login again
Verify fonts are installed:
fc-list | grep -i "JetBrains"
The script isn’t executable.Solution:
chmod +x ~/dotfiles/install.sh
./install.sh
The directory isn’t in your PATH.Solution:Add to your ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.local/bin:$PATH"
Then reload:
source ~/.zshrc
# or
source ~/.bashrc
Verify it’s in PATH:
echo $PATH | grep -o '.local/bin'

​
Theme Not Applying Correctly

The scripts weren’t stowed to ~/.local/bin.Solution:
cd ~/dotfiles
stow -v -R -t ~/.local/bin scripts

# Verify script exists
ls -la ~/.local/bin/theme-switcher

# Make sure it's executable
chmod +x ~/.local/bin/theme-switcher
Some components require manual reload.Solution:
# After running theme-switcher, manually reload:

# Reload Hyprland
hyprctl reload

# Restart Waybar
killall waybar && waybar &

# Reload Ghostty
killall -SIGUSR2 ghostty

# Reload Swaync
swaync-client -rs

# Close and reopen Wofi (no persistent daemon)
# Just launch it again: Super + Space
The theme-switcher script should do this automatically. If it doesn’t, the script might have errors.
The theme files are missing or not properly stowed.Solution:
# Check if theme files exist
ls -la ~/dotfiles/config/hypr/colors/custom/
ls -la ~/dotfiles/config/waybar/colors/custom/

# If they exist but aren't linked:
cd ~/dotfiles
stow -v -R -t ~/.config config

# Verify symlinks
ls -la ~/.config/hypr/colors/
ls -la ~/.config/waybar/colors/
The theme extension isn’t installed or the name is wrong.Solution:
  1. Check if the theme is installed in VSCodium:
    • Open VSCodium
    • Go to Extensions (Ctrl+Shift+X)
    • Search for the theme (e.g., “Kanagawa”, “Gruvbox”)
    • Install if not present
  2. Verify theme name in theme-switcher script: 
    nvim ~/dotfiles/scripts/theme-switcher

# Check the VSCODIUM_THEME variable matches exactly:
# Line ~33:
kanagawa)
  VSCODIUM_THEME="Kanagawa Wave"  # Must match extension name
  3. Check VSCodium settings: 
    cat ~/.config/VSCodium/User/settings.json | grep colorTheme
The colorscheme plugin isn’t installed or theme_bridge.lua is incorrect.Solution:
# Check theme bridge file
cat ~/.config/nvim/lua/theme_bridge.lua
# Should return something like: return 'kanagawa'

# Open Neovim and check for plugin errors
nvim
:checkhealth

# Install/sync plugins
:Lazy sync

# Try setting colorscheme manually
:colorscheme kanagawa
If the colorscheme isn’t installed:
# Add to your plugin config
# ~/.config/nvim/lua/plugins/colorscheme.lua
return {
  {
    "rebelot/kanagawa.nvim",
    lazy = false,
    priority = 1000,
  },
}
No wallpaper files match the theme name.Solution:
# Check for wallpapers
ls ~/.config/hypr/wallpapers/

# Wallpapers should be named: themename-description.png
# For example:
# kanagawa-wave.png
# gruvbox-mountain.png

# Add wallpaper for your theme
cp /path/to/wallpaper.png ~/.config/hypr/wallpapers/themename-wall.png

# Run theme switcher again
theme-switcher themename

​
Service Reload Issues

Configuration syntax error or missing module.Solution:
# Test Waybar in terminal to see errors
killall waybar
waybar

# Check for JSON syntax errors
cat ~/.config/waybar/config | jq .
cat ~/.config/waybar/modules.json | jq .

# Check logs
journalctl --user -u waybar -n 50
Common errors:
  • Missing comma in JSON
  • Invalid module name
  • Incorrect CSS color syntax
Hot-reload signal not working or old Ghostty version.Solution:
# Try reload signal
killall -SIGUSR2 ghostty

# If that doesn't work, fully restart
killall ghostty
# Then open new terminal (Super + T)

# Verify color file exists
cat ~/.config/ghostty/colors/colors
# Should show: config-file = custom/themename

# Check actual theme file
cat ~/.config/ghostty/colors/custom/kanagawa
CSS not reloading properly.Solution:
# Reload Swaync CSS
swaync-client -rs

# If that doesn't work, restart the daemon
killall swaync
swaync &

# Test notification
notify-send "Test" "This is a test notification"

# Check CSS file
cat ~/.config/swaync/colors/colors.css
Hyprpaper daemon isn’t running.Solution:
# Check if hyprpaper is running
pgrep hyprpaper

# If not running, start it
hyprpaper &

# Wait a second, then apply theme
theme-switcher kanagawa

# Add to autostart if missing
echo "exec-once = hyprpaper" >> ~/.config/hypr/autostart.conf
Wofi doesn’t have a daemon, it reads CSS on launch.Solution:Just close Wofi and reopen it:
# Press Escape to close Wofi
# Then reopen: Super + Space
Verify CSS is correct:
cat ~/.config/wofi/colors/colors.css
# Should have: @import url("/home/user/.config/wofi/colors/custom/themename.css");

​
Hyprland Configuration Errors

Syntax error in configuration files.Solution:
# Switch to TTY (Ctrl+Alt+F3)
# Login and check Hyprland logs
cat ~/.hyprland/hyprland.log | tail -50

# Or use journalctl
journalctl --user -xe | grep hyprland

# Test config syntax
hyprctl reload
# Will show line number of error
Common errors:
  • Missing source file
  • Invalid color format (missing rgb() wrapper)
  • Typo in variable name
  • Missing closing brace }
Theme variables not loaded or syntax error.Solution:
# Check if colors.conf is sourced
head -1 ~/.config/hypr/hyprland.conf
# Should have: source = ./colors/colors.conf

# Check colors.conf points to a theme
cat ~/.config/hypr/colors/colors.conf
# Should have: source = ~/.config/hypr/colors/custom/kanagawa.conf

# Verify theme file exists and has content
cat ~/.config/hypr/colors/custom/kanagawa.conf

# Test color syntax in hyprland.conf
# Correct:   col.active_border = rgb($blue)
# Wrong:     col.active_border = $blue
# Wrong:     col.active_border = rgb(#7E9CD8)
Conflict with existing binding or wrong key name.Solution:
# Check current bindings
hyprctl binds | grep -i "your-key"

# Test key name
# Run this, then press the key:
wev
# Note the key name it shows

# Check for conflicts in keybindings.conf
grep "your-key" ~/.config/hypr/keybindings.conf

# Reload after changes
hyprctl reload
Wrong monitor identifier or invalid settings.Solution:
# List available monitors
hyprctl monitors

# Check monitors.conf
cat ~/.config/hypr/monitors.conf

# Example correct syntax:
# monitor=DP-1,1920x1080@60,0x0,1
# monitor=,preferred,auto,1  # For all monitors

# Test with hyprctl
hyprctl keyword monitor "DP-1,1920x1080@60,0x0,1"
GPU driver issue or wrong animation config.Solution:
# Check if animations are enabled
cat ~/.config/hypr/animations.conf | grep "enabled"

# Test disabling animations
hyprctl keyword animations:enabled false

# If that fixes lag, reduce animation complexity:
# Edit animations.conf, reduce animation duration:
# animation = windows, 1, 2, default  # Reduced from 4 to 2

# Check GPU
glxinfo | grep "OpenGL renderer"

# For NVIDIA, ensure env vars are set in hyprland.conf:
# env = LIBVA_DRIVER_NAME,nvidia
# env = __GLX_VENDOR_LIBRARY_NAME,nvidia
Blur settings incompatible with GPU or wrong opacity.Solution:
# Check blur settings in hyprland.conf
cat ~/.config/hypr/hyprland.conf | grep -A 10 "blur {"

# Try simpler blur settings:
decoration {
    blur {
        enabled = true
        size = 5           # Reduced from 10
        passes = 1         # Reduced from 2
        ignore_opacity = true
    }
}

# Reload
hyprctl reload

# If still not working, disable xray:
blur {
    xray = false
}

​
Getting Help

Before asking for help, gather relevant information:
  • Output of failing command
  • Relevant log files
  • Your system info (neofetch or fastfetch)
  • What you’ve already tried

​
Useful Debug Commands

# Check Hyprland version
hyprctl version

# View Hyprland logs
cat ~/.hyprland/hyprland.log

# Check systemd user services
systemctl --user status

# View recent journal entries
journalctl --user -n 100

# Test if a program is running
pgrep -a waybar
pgrep -a hyprpaper

# Check symlink status
ls -la ~/.config/hypr
ls -la ~/.config/waybar

# Verify dotfiles stow status
cd ~/dotfiles
stow -n -v -t ~/.config config  # Dry run

​
Log Locations

~/.hyprland/hyprland.log          - Hyprland logs
~/.config/waybar/                 - Check terminal output
~/.cache/                         - Various app caches
journalctl --user                 - Systemd user logs

​
Common Log Patterns to Look For

# Errors in Hyprland log
grep -i "error" ~/.hyprland/hyprland.log

# Missing files
grep -i "no such file" ~/.hyprland/hyprland.log

# Config syntax errors
grep -i "syntax" ~/.hyprland/hyprland.log

​
Still Having Issues?

Hyprland Wiki

Official Hyprland documentation

GitHub Issues

Report bugs or ask questions

Arch Wiki

General Arch Linux help

Configuration Guide

Return to customization guide