Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shawal-mbalire/dotfiles/llms.txt

Use this file to discover all available pages before exploring further.

​
Setup Issues

Error: Tmux starts but plugins (tpm, catppuccin, etc.) are not working or showing errors.Solution:The Tmux Plugin Manager (tpm) needs to be installed manually. Run:
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
After installation:
  1. Start tmux or reload your configuration: tmux source ~/.config/tmux/tmux.conf
  2. Press Ctrl+Space then I (capital i) to install plugins
  3. Restart tmux sessions for changes to take effect
Reference: The configuration loads tpm at the end of tmux.conf:130
Error: Applications requiring elevated permissions fail silently or timeout.Solution:Install the Hyprland polkit authentication agent:
sudo dnf install hyprpolkitagent
The agent is configured to start automatically in modules/autostart.conf:20:
exec-once = systemctl --user start hyprpolkitagent
If still not working, verify the service is running:
systemctl --user status hyprpolkitagent
Error: Icons appear as boxes, waybar modules show [] instead of symbols, or fonts look incorrect.Solution:Install the required Nerd Fonts:For Arch Linux:
yay -S ttf-hack-nerd
For Fedora:
sudo dnf copr enable zawertun/hack-fonts
sudo dnf install hack-fonts
JetBrainsMono Nerd Font (alternative):
curl -OL https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.tar.xz
tar -xf JetBrainsMono.tar.xz -C ~/.local/share/fonts/
fc-cache -fv
After installation, log out and log back in to ensure fonts are loaded.
Error: stow command fails with “existing target is not owned by stow” errors.Solution:Backup and remove conflicting files before running stow:
# Example for a specific conflict
mv ~/.config/hypr ~/.config/hypr.backup

# Then re-run stow from your dotfiles directory
stow .
Understanding .stowrc: The .stowrc configuration uses:
  • --target=~ - Installs to home directory
  • --dotfiles - Converts dot- prefix to . in target
  • --ignore=.stowrc - Doesn’t symlink the stow config itself

​
Hyprland Issues

Error: External monitor not showing up, wrong resolution, or positioned incorrectly.Solution:
  1. List available outputs:
hyprctl monitors
  1. Check your monitor configuration in the appropriate config file:
    • Desktop: ~/.config/hypr/modules/displays.conf
    • Laptop: ~/.config/hypr/modules/displays-laptop.conf
  2. The default configurations use:
    • Primary: eDP-1,1920x1200@60,0x0,1
    • Secondary: HDMI-A-2,1600x900@60,1921x0,1
  3. Update the monitor variables in your config: 
$primary_monitor = YOUR-OUTPUT,1920x1080@60,0x0,1
  1. Reload Hyprland: Super + Shift + R or hyprctl reload
Error: Black screen after login, or immediate crash to TTY.Solution:
  1. Check Hyprland logs:
cat /tmp/hypr/$(ls -t /tmp/hypr/ | head -1)/hyprland.log
  1. Common causes:
    • Missing dependencies: Verify all autostart applications are installed
    • Invalid config syntax: Check for typos in hyprland.conf
    • Missing module files: Ensure all imported modules exist
  2. Test with minimal config: 
# Temporarily rename your config
mv ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.backup

# Start with defaults
Hyprland
  1. If working, gradually re-enable modules to identify the problematic one.
Error: Keybindings for workspace switching have no effect.Solution:
  1. Verify keybindings are loaded:
hyprctl binds | grep workspace
  1. Check modules/keybindings.conf is properly sourced in your main config
  2. Test if the mod key is working: 
# Check what $mainMod is set to (should be SUPER)
grep mainMod ~/.config/hypr/hyprland.conf
  1. Reload configuration: Super + Shift + R
Error: Waybar, notification daemon, or other autostart apps don’t start with Hyprland.Solution:Check modules/autostart.conf for the list of autostart applications:
  • nm-applet - Network manager
  • blueman-applet - Bluetooth
  • mako - Notifications
  • hyprpolkitagent - Authentication
  • hyprpaper - Wallpaper
Verify each application is installed:
which nm-applet blueman-applet mako hyprpaper
If missing, install the required packages:
sudo dnf install network-manager-applet blueman mako hyprpaper
Check for errors in the Hyprland log after login.

​
Waybar Issues

Error: Waybar doesn’t show after login or becomes invisible.Solution:
  1. Check if waybar is running:
pgrep waybar
  1. Manually start waybar to see errors:
killall waybar
waybar
  1. Check the configuration syntax:
waybar -c ~/.config/waybar/config.jsonc -s ~/.config/waybar/style.css
  1. Verify dependencies are installed:
sudo dnf install waybar jetbrains-mono-fonts sono-fonts pavucontrol brightnessctl
Error: Specific waybar modules display errors, show “N/A”, or are empty.Solution:Common module issues:Network module:
  • Requires network-manager-applet
  • Check: nmcli device status
Power profile module:
  • Requires power-profiles-daemon
  • Install: sudo dnf install power-profiles-daemon
  • Enable: systemctl enable --now power-profiles-daemon
Battery module:
  • Only works on laptops
  • Check battery path: ls /sys/class/power_supply/
Check waybar logs:
journalctl --user -u waybar -f
Solution:Method 1: Kill and restart (hard reload)
killall waybar && waybar &
Method 2: Soft reload (SIGUSR2)
killall -SIGUSR2 waybar
Method 3: Using Justfile If you have just installed:
cd ~/.config/waybar
just reload    # Soft reload
just restart   # Hard restart
Method 4: Hyprland keybind Use Super + Shift + R if configured in your keybindings.Note: Hard reload is needed for structural config changes, soft reload works for style updates.

​
Application Issues

Error: Flatpak apps like Zen Browser or Quran Companion don’t start.Solution:
  1. Verify the application is installed:
flatpak list
  1. Install if missing:
# Zen Browser
flatpak install flathub app.zen_browser.zen

# Or your specific application
flatpak search <app-name>
  1. Check permissions:
flatpak override --user --show app.zen_browser.zen
  1. Run from terminal to see errors:
flatpak run app.zen_browser.zen
Error: Application launcher doesn’t appear or uses default theme instead of gridmenu.Solution:The configuration uses a custom rofi theme. Verify:
  1. Check rofi is installed:
which rofi
  1. Test the exact command from config:
rofi -show drun -theme launchers/gridmenu -drun-icon-theme "BeautySolar"
  1. If theme is missing, check your rofi themes directory:
ls ~/.config/rofi/launchers/
  1. The theme path should exist or use a different installed theme:
rofi-theme-selector
Error: Clipboard manager (cliphist) doesn’t store or recall clipboard history.Solution:The autostart configuration includes:
exec-once = wl-paste --watch cliphist store &
  1. Install cliphist:
# Arch
yay -S cliphist

# Fedora (may need to build from source)
go install go.senan.xyz/cliphist@latest
  1. Verify wl-paste is running:
pgrep -a wl-paste
  1. Test clipboard storage:
echo "test" | wl-copy
cliphist list

​
Configuration Issues

Solution:After modifying configuration files:For Hyprland:
hyprctl reload
Or use keybind: Super + Shift + RFor Waybar:
killall waybar && waybar &
For Tmux:
tmux source ~/.config/tmux/tmux.conf
Or inside tmux: Ctrl+Space then :source ~/.config/tmux/tmux.confFor complete reload: Log out and log back in to Hyprland
Solution:Use local override files that are gitignored:Tmux local config: Create ~/.config/tmux/tmux.local.conf for your customizations. This file is automatically sourced at tmux.conf:127:
if-shell "[ -f ~/.config/tmux/tmux.local.conf ]" 'source ~/.config/tmux/tmux.local.conf'
Hyprland local config: Add a source line at the end of your hyprland.conf:
source = ~/.config/hypr/local.conf
This follows the 12-factor approach of separating config from environment-specific settings.

​
Getting More Help

If your issue isn’t covered here:
  1. Check the FAQ for additional questions
  2. Review the Hyprland wiki: https://wiki.hyprland.org
  3. Check application-specific logs in /tmp or ~/.local/share/
  4. Run applications from terminal to see error output
  5. Review your specific module configuration in ~/.config/hypr/modules/

Build docs developers (and LLMs) love

Get started for freeTalk to us