Skip to main content
This page covers common issues you might encounter when setting up or using these dotfiles, along with their solutions.

​
Installation issues

If you encounter errors about missing commands or tools after installation:Solution:
  1. Verify all packages from the installation sections in the README are installed
  2. Check which package manager you’re using (Arch/yay vs Ubuntu/apt)
  3. Some tools like eza and zoxide may need to be installed via cargo on non-Arch systems: 
    cargo install eza zoxide
  4. Ensure your PATH includes cargo binaries: ~/.cargo/bin
Verification:
which eza zoxide fzf
All commands should return their installation paths.
When running stow . you may encounter conflicts if files already exist.Solution:
  1. Backup your existing dotfiles: 
    mkdir ~/dotfiles-backup
mv ~/.zshrc ~/.config/nvim ~/dotfiles-backup/
  2. Try restowing to refresh symlinks: 
    stow --restow .
  3. For persistent conflicts, use the --adopt flag (this will replace the repo files with your local ones): 
    stow --adopt .
git restore .  # Restore original dotfiles after adopting
Prevention: Always backup your configuration before stowing new dotfiles.
After setting Zsh as default shell, your terminal still shows bash or another shell.Solution:
  1. Verify Zsh is set as default: 
    echo $SHELL
    Should show: /usr/bin/zsh or /bin/zsh
  2. If not set correctly, run: 
    chsh -s $(which zsh)
  3. Completely log out and log back in (or reboot)
  4. On some systems, you may need to update /etc/passwd manually or use sudo chsh -s $(which zsh) $USER
Verification: Open a new terminal and run:
echo $SHELL
ps -p $$

​
Hyprland issues

Hyprland fails to start from the display manager or crashes immediately.Solution:
  1. Check Hyprland logs: 
    journalctl --user -u hyprland -b
  2. Verify required dependencies are installed: 
    yay -S hyprland hyprpaper waybar wofi mako
  3. Check for configuration syntax errors: 
    hyprland --config ~/.config/hypr/hyprland.conf --dry-run
  4. Ensure your GPU drivers are properly installed:
    • NVIDIA: Install nvidia-dkms and enable DRM kernel mode
    • AMD/Intel: Ensure mesa drivers are installed
  5. Try starting Hyprland from TTY (Ctrl+Alt+F2): 
    Hyprland
Common causes:
  • Missing Wayland support in GPU drivers
  • Conflicting window manager processes
  • Invalid configuration syntax
The status bar doesn’t show up when Hyprland starts.Solution:
  1. Check if the process is running: 
    ps aux | grep -E 'ags|waybar'
  2. Try launching manually to see errors: 
    agsv1  # or waybar
  3. Verify the autostart line in ~/.config/hypr/hyprland.conf: 
    exec-once = agsv1 & hyprpaper
  4. Check AGS/Waybar configuration files for errors
  5. Install missing dependencies (check AGS documentation)
Workaround: Switch to Waybar if AGS is problematic:
exec-once = waybar & hyprpaper
Swaylock doesn’t activate or shows errors.Solution:
  1. Verify swaylock is installed: 
    which swaylock
  2. Check the wallpaper path in ~/.config/hypr/hyprland.conf: 
    bindl=SUPER,L,exec, swaylock -f -e -l -L -s fill -i ~/dotfiles/Wallpaper/street-tn.png
  3. Update the path to an existing wallpaper or remove the -i flag: 
    swaylock -f -e -l -L
  4. Ensure you have permission to use swaylock (may need to be in certain groups)

​
Tmux issues

Plugins don’t install after pressing Ctrl+a I.Solution:
  1. Install TPM manually: 
    git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
  2. Reload tmux configuration: 
    tmux source ~/.config/tmux/tmux.conf
  3. Inside tmux, press Ctrl+a then I (capital i) to install plugins
  4. Wait for installation to complete (may take 30-60 seconds)
Verification:
ls ~/.tmux/plugins/
Should show multiple plugin directories.
Colors appear incorrect or washed out in tmux.Solution:
  1. Ensure your terminal supports true color. Add to your shell rc file: 
    export TERM=xterm-256color
  2. Verify tmux configuration has true color support: 
    set-option -sa terminal-overrides ",xterm*:Tc"
  3. Restart tmux completely: 
    tmux kill-server
tmux
  4. Check if your terminal emulator (Ghostty/Kitty) is set to support true color
The Ctrl+a prefix doesn’t respond.Solution:
  1. Verify the prefix is set in ~/.config/tmux/tmux.conf: 
    set-option -g prefix C-a
bind-key C-a send-prefix
  2. Reload configuration: 
    tmux source ~/.config/tmux/tmux.conf
  3. Check for conflicting keybindings in your shell (Ctrl+a is also readline’s beginning-of-line)
  4. Try the old prefix Ctrl+b to see if tmux responds at all

​
Kanata issues

Kanata service is running but Caps Lock doesn’t behave as configured.Solution:
  1. Check service status: 
    systemctl --user status kanata
  2. View service logs for errors: 
    journalctl --user -u kanata -f
  3. Verify configuration syntax: 
    kanata --check --cfg ~/.config/kanata/config.kbd
  4. Ensure you have proper permissions. Kanata may need:
    • Access to /dev/uinput
    • User to be in input or uinput group: 
      sudo usermod -aG input $USER
sudo usermod -aG uinput $USER
    • Logout and login for group changes to take effect
  5. Restart the service: 
    systemctl --user restart kanata
Alternative: Run kanata manually to see errors:
kanata --cfg ~/.config/kanata/config.kbd
Kanata doesn’t start automatically after system boot.Solution:
  1. Enable the service: 
    systemctl --user enable kanata.service
  2. Check service file location: 
    ls ~/.config/systemd/user/kanata.service
  3. Reload systemd daemon: 
    systemctl --user daemon-reload
  4. Verify the ExecStart path in the service file points to the correct kanata binary: 
    which kanata
  5. Check for errors preventing service start: 
    systemctl --user status kanata

​
Font issues

You see boxes or missing characters instead of icons.Solution:
  1. Install Nerd Fonts: 
    yay -S ttf-jetbrains-mono-nerd
  2. Refresh font cache: 
    fc-cache -fv
  3. Verify the font is installed: 
    fc-list | grep -i jetbrains
  4. Update terminal configuration to use Nerd Font:
    • Ghostty: Set font-family = JetBrainsMono Nerd Font
    • Kitty: Set font_family JetBrains Mono Nerd Font
  5. Restart your terminal
For Oh My Posh: Ensure you’re using a Nerd Font. Oh My Posh requires Nerd Font glyphs for icons.

​
Development tool issues

Neovim starts but plugins aren’t working or showing errors.Solution:
  1. Open Neovim and run: 
    :Lazy sync
  2. Check for errors: 
    :checkhealth
  3. Ensure required dependencies are installed: 
    # Clipboard support
yay -S xclip wl-clipboard

# Language servers and tools
yay -S ripgrep fd
  4. Update LazyVim: 
    :Lazy update
  5. If using a git submodule for nvim config, update it: 
    cd ~/dotfiles
git submodule update --init --recursive
Commands like eza, zoxide, or custom aliases don’t work.Solution:
  1. Ensure the tool is installed: 
    which eza  # or the command in question
  2. Check your PATH: 
    echo $PATH
  3. Source your shell configuration: 
    source ~/.zshrc
  4. For cargo-installed tools, ensure ~/.cargo/bin is in PATH: 
    export PATH="$HOME/.cargo/bin:$PATH"
  5. Restart your shell or terminal completely

​
Getting more help

If you encounter issues not covered here:
  1. Check the logs for the specific component
  2. Review the configuration files for syntax errors
  3. Consult the official documentation for each tool
  4. Open an issue on the dotfiles repository with:
    • Your system information (uname -a)
    • Steps to reproduce the issue
    • Relevant log output
    • What you’ve already tried

Build docs developers (and LLMs) love

Get started for freeTalk to us