Table of Contents

• Introduction
• Understanding Log Files
  • Hyprland Logs (~/.cache/hyprland/hyprland.log)
  • Systemd Journal (journalctl)
  • Waybar Logs
• Common Debugging Scenarios
  • Hyprland Not Starting
  • Application Crashes
  • Keybindings Not Working
  • Theming/Display Issues
  • Audio Problems
• Useful Debugging Tools
  • hyprctl
  • fastfetch
  • yay
  • pacman
  • strace
• Resetting Configuration
• Seeking Further Help

Introduction

Debugging is an essential skill for any Linux user, especially when working with a highly customizable environment like HyprL. This guide will walk you through common debugging techniques, how to interpret log files, and which tools to use to diagnose and resolve issues in your HyprL setup.

Understanding Log Files

Log files are your first line of defense when something goes wrong. They provide valuable clues about errors, warnings, and system behavior.

Hyprland Logs (~/.cache/hyprland/hyprland.log)

This is the primary log file for the Hyprland compositor. It records startup messages, errors, warnings, and information about window management, rendering, and input.

To view the latest Hyprland logs:

cat ~/.cache/hyprland/hyprland.log

To follow the log in real-time (useful when reproducing an issue):

tail -f ~/.cache/hyprland/hyprland.log

Systemd Journal (journalctl)

Systemd manages most services on Arch Linux, and journalctl is the utility to query its journal. This is crucial for debugging user-level services (like PipeWire, Waybar, SwayNC) and system-level issues.

To view all user-specific logs (useful for desktop environment components):

journalctl --user

To view logs for a specific service (e.g., PipeWire):

journalctl --user -u pipewire.service

To follow logs in real-time:

journalctl -f

Waybar Logs

Waybar often logs its output to the systemd journal. You can view its logs specifically:

journalctl --user -u waybar.service -f

Common Debugging Scenarios

Hyprland Not Starting

If Hyprland fails to start (e.g., you’re dropped back to a TTY or login manager):

1. Check ~/.cache/hyprland/hyprland.log: Look for [ERROR] messages. Common issues include syntax errors in hyprland.conf or missing dependencies.
2. Try a minimal config: Temporarily move your hyprland.conf and try starting Hyprland. If it works, the issue is in your configuration. You can move it back and comment out sections until you find the culprit.

   mv ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.bak
   # Try starting Hyprland
   mv ~/.config/hypr/hyprland.conf.bak ~/.config/hypr/hyprland.conf

3. Check ~/.zprofile: Ensure it correctly executes Hyprland on TTY1.

Application Crashes

If a specific application crashes:

1. Run from terminal: Open a terminal (if possible) and launch the application from there. Look for any error messages printed to the console.
2. Check application-specific logs: Many applications have their own log files, often in ~/.local/share/ or ~/.cache/.
3. Systemd Journal: Check journalctl --user for any related errors.

Keybindings Not Working

1. Verify hyprctl: Ensure hyprctl commands work directly in a terminal (e.g., hyprctl dispatch exec kitty). If not, Hyprland might not be running or hyprctl is not in your PATH.
2. Check keybindings.conf: Review ~/.config/hypr/conf/keybindings/default.conf for typos or incorrect syntax.
3. Reload Hyprland: After any changes to keybindings, run hyprctl reload.
4. Check for conflicts: Ensure no other application or service is intercepting the keybinding.

Theming/Display Issues

(e.g., Waybar not appearing, wrong resolution, missing icons)

1. Waybar: Restart Waybar with ~/.config/waybar/launch.sh. Check journalctl --user -u waybar.service.
2. Monitors: Use hyprctl monitors to see how Hyprland detects your displays. Check ~/.config/hypr/conf/monitors/default.conf.
3. Fonts/Icons: Run fc-cache -fv to refresh font caches. Ensure icon themes are installed and correctly configured (e.g., in ~/.gtkrc-2.0 or application-specific configs).
4. Wallpaper: Check ~/.wallpaper/ for images. Manually set with swww img /path/to/image.jpg. Check swww query.

Audio Problems

1. Check PipeWire status: systemctl --user status pipewire pipewire-pulse wireplumber.
2. Restart audio services: systemctl --user restart pipewire pipewire-pulse wireplumber.
3. Check devices: Use pactl list sinks and pactl list sources to see detected audio devices.
4. Volume control: Use pavucontrol to check volume levels and output devices.

Useful Debugging Tools

hyprctl

The command-line utility for interacting with a running Hyprland instance. Essential for querying state and dispatching commands.

hyprctl clients         # List active windows
hyprctl monitors        # List connected monitors
hyprctl workspaces      # List workspaces
hyprctl dispatch <cmd>  # Dispatch a command

fastfetch

A system information tool that provides a quick overview of your hardware and software environment. Useful for sharing system specs when seeking help.

fastfetch

yay

Your AUR helper for installing and managing packages. Use it to check if packages are installed or to reinstall them.

yay -Qi <package_name>  # Query installed package info
yay -S <package_name>   # Install/reinstall a package

pacman

The official Arch Linux package manager.

pacman -Qi <package_name> # Query installed package info
pacman -Syu               # Update system

strace

(Advanced) Traces system calls and signals. Can be very verbose but powerful for deep debugging.

strace <command> # e.g., strace kitty

Resetting Configuration

As a last resort, if you suspect your configuration is corrupted, you can reset parts of it to the HyprL defaults. Always back up your current configuration first!

1. Backup: cp -r ~/.config ~/.config-backup-$(date +%s)
2. Remove problematic configs: rm -rf ~/.config/hypr ~/.config/waybar ~/.config/rofi (or specific files)
3. Re-run installer: bash <(curl -sL https://raw.githubusercontent.com/Manpreet113/hyprL/master/main/setup.sh) (this will redeploy default configs).

Seeking Further Help

If you’ve exhausted these options and still can’t resolve your issue:

1. Check TROUBLESHOOTING.md: The top-level TROUBLESHOOTING.md file in the project root contains a concise list of common issues and solutions.
2. GitHub Issues: Search the HyprL GitHub Issues page for similar problems.
3. Create a new issue: If your problem isn’t listed, create a new issue. Include:
   • Your system information (fastfetch output).
   • A detailed description of the problem.
   • Steps to reproduce the issue.
   • Any relevant log file snippets (Hyprland, journalctl, etc.).
4. Community Support: Join the HyprL Discord server for real-time assistance from the community.