Skip to main content
This guide covers common issues you might encounter and how to resolve them.

​
Installation Issues

​
Paru Not Installed

Problem: The install script fails because Paru is not available. Solution: Install Paru manually before running the dotfiles installer: 
# Install build dependencies
sudo pacman -S --needed base-devel git

# Clone and build Paru
git clone https://aur.archlinux.org/paru.git
cd paru
makepkg -si
cd ..
rm -rf paru
Then run the dotfiles installer: 
cd ~/dotfiles
./install

​
Git Submodules Missing

Problem: Dotbot or other submodules are missing. Error: fatal: not a git repository or empty directories Solution: 
cd ~/dotfiles

# Initialize and update submodules
git submodule init
git submodule update --recursive

# Or re-clone with submodules
cd ~
rm -rf dotfiles
git clone --recurse-submodules https://github.com/your-repo/dotfiles

​
Package Installation Fails

Problem: Some packages fail to install during setup. Solution:
  1. Update system first: 
    sudo pacman -Syu
  2. Check for conflicts: 
    paru -S package-name
# Read error messages carefully
  3. Install problematic packages manually: 
    # Skip in packages.txt temporarily
paru -S problematic-package
  4. Check AUR package status:
Some AUR packages may be out-of-date or broken. Check the AUR page for alternatives or fixes.

​
Permission Denied Errors

Problem: Installation fails with permission errors. Solution: 
# Make install script executable
chmod +x ~/dotfiles/install

# Ensure proper ownership
sudo chown -R $USER:$USER ~/dotfiles

​
Hyprland Not Starting

​
Black Screen on Launch

Problem: Hyprland launches but shows only a black screen. Solution:
  1. Check Hyprland logs: 
    cat /tmp/hypr/$(ls -t /tmp/hypr/ | head -n 1)/hyprland.log
  2. Test with minimal config: 
    # Backup current config
mv ~/.config/hypr ~/.config/hypr.backup

# Create minimal config
mkdir -p ~/.config/hypr
echo 'exec-once = kitty' > ~/.config/hypr/hyprland.conf

# Launch Hyprland
Hyprland
  3. Check autostart errors:
    • Edit ~/.config/hypr/modules/autostart.conf
    • Comment out autostart applications one by one
    • Find which application is causing the issue

​
Hyprland Crashes on Startup

Problem: Hyprland immediately crashes when launched. Solution:
  1. Check for missing dependencies: 
    paru -S qt6-wayland xdg-desktop-portal-hyprland
  2. Verify GPU drivers: 
    # For NVIDIA (if applicable)
paru -S nvidia-dkms nvidia-utils

# For AMD
paru -S mesa vulkan-radeon

# For Intel
paru -S mesa vulkan-intel
  3. Check environment variables:
    • Edit ~/.config/hypr/modules/env.conf
    • Comment out GPU-specific variables if needed
  4. Launch from TTY with debug output: 
    Hyprland 2>&1 | tee ~/hyprland-debug.log

​
Monitor Configuration Issues

Problem: Displays not detected or incorrectly configured. Solution:
  1. List available monitors: 
    hyprctl monitors
  2. Edit monitor configuration: 
    # ~/.config/hypr/modules/monitors.conf

# Auto-detect (default)
monitor = ,preferred,auto,1

# Or specify explicitly
monitor = HDMI-A-1,1920x1080@60,0x0,1
  3. Reload configuration: 
    hyprctl reload

​
Application Configuration Problems

​
Waybar Not Appearing

Problem: Waybar doesn’t show up after starting Hyprland. Solution:
  1. Check if Waybar is running: 
    pgrep waybar
  2. Start Waybar manually: 
    waybar &
  3. Check Waybar logs: 
    waybar --log-level debug
  4. Verify configuration: 
    # Test config syntax
waybar --config ~/.config/waybar/config.json --style ~/.config/waybar/style.css
  5. Common config issues:
    • Missing dependencies: paru -S otf-font-awesome
    • Invalid JSON in config.json
    • CSS syntax errors in style.css

​
Rofi Won’t Launch

Problem: Pressing Super + Space doesn’t open Rofi. Solution:
  1. Test Rofi manually: 
    rofi -show drun
  2. Check Rofi config: 
    rofi -show drun -config ~/.config/rofi/config.rasi
  3. Verify keybinding: 
    # ~/.config/hypr/modules/binds.conf
bind = $mainMod, SPACE, exec, $menu
  4. Check menu variable: 
    # ~/.config/hypr/modules/vars.conf
$menu = rofi -show drun

​
Kitty Terminal Not Opening

Problem: Super + Return doesn’t launch Kitty. Solution:
  1. Launch from Rofi:
    • Press Super + Space
    • Type “kitty”
    • Check for error messages
  2. Test Kitty directly: 
    kitty
  3. Check Kitty config: 
    kitty --debug-config
  4. Verify terminal variable: 
    # ~/.config/hypr/modules/vars.conf
$terminal = kitty

​
Screenshots Not Working

Problem: Screenshot keybindings don’t work. Solution:
  1. Ensure screenshot tools are installed: 
    paru -S hyprshot grim slurp satty wl-clipboard
  2. Create screenshots directory: 
    mkdir -p ~/Pictures/Screenshots
  3. Test manually: 
    # Full screen
hyprshot -m output --clipboard-only

# Region
hyprshot -m region --clipboard-only
  4. Check keybindings: 
    # ~/.config/hypr/modules/binds.conf
bind = , Print, exec, hyprshot -m output --raw | satty --filename - --output-filename ~/Pictures/Screenshots/$(date '+%Y%m%d-%H%M%S').png

​
Package Conflicts

​
Package X and Y are in Conflict

Problem: Installing a package fails due to conflicts. Solution:
  1. Identify the conflict: 
    paru -Si conflicting-package
  2. Remove the conflicting package: 
    paru -R old-package
paru -S new-package
  3. Check package provides: Some packages provide the same functionality: 
    pacman -Qi package-name | grep Provides
Known Issue: The packages.txt file includes swaync, but the actual configuration uses mako for notifications. This is a discrepancy in the dotfiles repository. The system is configured to use mako (in autostart.conf and install.conf.yaml), so you can safely skip installing swaync.

​
Dependency Cycle Detected

Problem: Package installation fails with circular dependencies. Solution: 
# Update package databases
paru -Sy

# Force database refresh
paru -Syyu

# If still failing, install dependencies manually
paru -S dependency1 dependency2
paru -S main-package
Problem: Installation fails with symlink errors. Solution:
  1. Remove existing files: 
    # Backup first
mv ~/.config/hypr ~/.config/hypr.old

# Re-run installer
cd ~/dotfiles
./install
  2. Check for broken symlinks: 
    # Find broken symlinks
find ~/.config -xtype l

# Remove broken symlinks
find ~/.config -xtype l -delete
  3. Force relink: 
    # In install.conf.yaml
- defaults:
    link:
      relink: true
      force: true

​
Configuration Changes Not Taking Effect

Problem: Editing configs in .config doesn’t change anything. Solution:
Don’t edit files in ~/.config/ directly! They are symlinks to ~/dotfiles/.
Correct workflow:
  1. Edit source files: 
    # Edit the source in dotfiles
nvim ~/dotfiles/hyprland/hypr/modules/binds.conf
  2. Changes apply automatically (symlinks point to source files)
  3. Reload Hyprland: 
    hyprctl reload
# Or: Super + Shift + R

​
Font and Icon Issues

​
Icons Not Displaying in Waybar/Rofi

Problem: Icons show as boxes or question marks. Solution:
  1. Install Nerd Fonts: 
    paru -S ttf-jetbrains-mono-nerd ttf-nerd-fonts-symbols
  2. Install Font Awesome: 
    paru -S otf-font-awesome ttf-font-awesome
  3. Rebuild font cache: 
    fc-cache -fv
  4. Verify font installation: 
    fc-list | grep -i nerd
fc-list | grep -i awesome
  5. Restart applications: 
    killall waybar && waybar &

​
Emoji Not Rendering

Problem: Emoji characters don’t display correctly. Solution: 
# Install emoji fonts
paru -S noto-fonts-emoji

# Rebuild font cache
fc-cache -fv

​
Audio Issues

​
Volume Keys Not Working

Problem: Media keys don’t control volume. Solution:
  1. Check if PipeWire/PulseAudio is running: 
    systemctl --user status pipewire pipewire-pulse
  2. Start audio services: 
    systemctl --user enable --now pipewire pipewire-pulse
  3. Test volume control: 
    wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
  4. Verify keybindings: 
    # ~/.config/hypr/modules/binds.conf
bindel = , XF86AudioRaiseVolume, exec, wpctl set-volume -l 1 @DEFAULT_AUDIO_SINK@ 5%+

​
No Audio Output

Problem: No sound from any application. Solution: 
# Install audio packages
paru -S pipewire pipewire-pulse pipewire-alsa pavucontrol

# Start services
systemctl --user enable --now pipewire pipewire-pulse

# Open volume control
pavucontrol
In PavuControl:
  1. Check “Output Devices” tab
  2. Ensure correct device is selected
  3. Unmute and adjust volume

​
Performance Issues

​
High CPU Usage

Problem: Hyprland uses excessive CPU. Solution:
  1. Reduce animation speed: 
    # ~/.config/hypr/modules/theme.conf
animations {
    enabled = yes
    
    # Lower speed multipliers
    animation = windows, 1, 3, myBezier  # was 7
    animation = workspaces, 1, 3, easeInOutQuad  # was 6
}
  2. Reduce blur: 
    decoration {
    blur {
        enabled = false  # or reduce size/passes
    }
}
  3. Disable shadows: 
    decoration {
    shadow {
        enabled = false
    }
}

​
Laggy Window Movements

Problem: Windows stutter when moving or resizing. Solution:
  1. Disable animations temporarily: 
    animations {
    enabled = no
}
  2. Reduce decoration effects: 
    decoration {
    dim_inactive = false
    blur { enabled = false }
}
  3. Check GPU usage: 
    # Monitor GPU
htop  # or btop

​
Getting Help

​
Where to Report Issues

For issues specific to this dotfiles configuration:
  1. Check existing issues on GitHub
  2. Create a new issue with:
    • Your system info (uname -a)
    • Hyprland version (hyprctl version)
    • Error messages or logs
    • Steps to reproduce
For Hyprland bugs or feature requests:

​
Collecting Debug Information

When reporting issues, include: 
# System information
uname -a

# Hyprland version
hyprctl version

# Package versions
pacman -Q hyprland waybar rofi kitty

# Hyprland log
cat /tmp/hypr/$(ls -t /tmp/hypr/ | head -n 1)/hyprland.log

# Check for errors
journalctl --user -b | grep -i error

​
Preventive Maintenance

Regular maintenance tasks to avoid issues:
# Weekly: Update system
paru -Syu

# Monthly: Clean package cache
paru -Sc

# Monthly: Remove orphaned packages
paru -Rns $(paru -Qtdq)

# As needed: Check for errors
journalctl --user -p 3 -b

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us