H
HyprL

Common Issues and Solutions

Even with the best setup, sometimes things don’t go as planned. This guide is here to help you troubleshoot common issues you might encounter with HyprL and Hyprland. We’ll cover problems from installation to daily use, with simple steps to get you back on track.

Table of Contents

🚀 Installation Problems

Script Fails to Install Packages

Sometimes, the installation script might get stuck or fail when trying to install software packages. This can happen due to internet issues, corrupted package lists, or problems with the package manager (yay).

What to do:

  1. Check your internet connection: Make sure you are connected to the internet.
  2. Try installing manually: If you know which package failed, you can try installing it by opening a terminal and typing:
    yay -S <package-name>

(Replace <package-name> with the actual name, e.g., yay -S firefox). 3. Update your system’s security keys: Sometimes, package signatures get outdated. Run:

sudo pacman -S archlinux-keyring

Then try the installation again.

Permission Denied on Scripts

If you see “Permission denied” errors when the system tries to run certain scripts, it means those scripts don’t have the necessary permissions to be executed.

What to do:

  • Open a terminal and run this command. It will make all necessary scripts executable:
find ~/.config -name "*.sh" -exec chmod +x {} \;

This command looks for all files ending in .sh (shell scripts) within your configuration folders and gives them permission to run.

🖥️ Display and Graphics Issues

Hyprland Won’t Start or Shows a Black Screen

This is a common issue where Hyprland doesn’t load correctly, leaving you with a black screen or returning you to the login prompt.

What to do:

  1. Check Hyprland’s log file: This file often contains clues about what went wrong. Open a terminal (you might need to switch to a TTY by pressing Ctrl + Alt + F2 or F3) and type:
cat ~/.cache/hyprland/hyprland.log

Look for error messages, especially lines marked with [ERROR]. 2. Try with a basic configuration: Your custom settings might be causing the problem. You can temporarily move your main Hyprland config file to see if a default setup works:

mv ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.bak

Then try starting Hyprland again. If it works, the issue is in your hyprland.conf or one of the files it includes.

Wrong Screen Resolution or Monitor Setup

Your monitors might not be detected correctly, or the resolution might be wrong.

What to do:

  1. List detected monitors: In a terminal, run:
hyprctl monitors

This will show you what Hyprland sees regarding your connected displays. 2. Edit monitor configuration: Your monitor settings are usually in ~/.config/hypr/conf/monitors/default.conf. You can open it with a text editor (like nvim or nano):

nano ~/.config/hypr/conf/monitors/default.conf

Adjust the resolution and position settings as needed. 3. Use a graphical tool: For an easier way to set up monitors, you can use nwg-displays:

nwg-displays

Screen Tearing or Performance Issues

If your screen looks like it’s tearing (horizontal lines appearing during movement) or if the system feels slow, especially with animations.

What to do:

  • Graphics Card Specific Settings:
    • NVIDIA Users: If you have an NVIDIA graphics card, you might need to enable specific settings. Check the file ~/.config/hypr/conf/environments/nvidia.conf and ensure it’s correctly set up or uncommented if it was commented out.
    • Virtual Machine (VM) Users: If you’re running HyprL in a virtual machine, enable settings specific to VMs by checking ~/.config/hypr/conf/environments/kvm.conf.
  • Adjust Animations: Hyprland has many beautiful animations, but they can sometimes impact performance. You can fine-tune or disable them in the files located in ~/.config/hypr/conf/animations/.

🎨 Theming and Appearance Issues

Waybar (Top Bar) Not Loading Correctly or Missing Theme

Waybar is the customizable bar at the top (or bottom) of your screen. If it looks wrong or doesn’t appear, its configuration or theme might be off.

What to do:

  1. Restart Waybar: Open a terminal and run:
~/.config/waybar/launch.sh

This script restarts Waybar with its correct settings. 2. Check theme selection: The theme for Waybar is often set in ~/.config/hyprL/settings/waybar-theme.sh. You can view its content with:

cat ~/.config/hyprL/settings/waybar-theme.sh
  1. Manually switch theme: You can try to force a theme switch using:

~/.config/waybar/themeswitcher.sh


### Missing Icons/Fonts
Missing icons or fonts usually indicate a caching issue or uninstalled fonts.

```bash
# Refresh font cache
fc-cache -fv

# Install common missing fonts (example)
yay -S ttf-font-awesome noto-fonts-emoji

# Check if a specific font is available
fc-list | grep -i "font-name"

Wallpaper Issues

Wallpaper Not Loading

If your wallpaper isn’t appearing, check the directory and swww status.

# Check wallpaper directory contents
ls ~/.wallpaper/

# Manually set wallpaper
~/.config/hypr/scripts/wallpaper.sh

# Check swww status
swww query

Wallpaper Automation Not Working

If automated wallpaper changes aren’t happening, check and restart the automation script.

# Check the automation script
~/.config/hypr/scripts/wallpaper-automation.sh

# Restart automation (kills existing process and starts a new one)
pkill -f wallpaper-automation
~/.config/hypr/scripts/wallpaper-automation.sh &

Audio Issues

No Audio Output

Audio problems often stem from PipeWire issues.

# Check PipeWire service status
systemctl --user status pipewire pipewire-pulse wireplumber

# Restart audio services
systemctl --user restart pipewire pipewire-pulse wireplumber

# Check available audio devices
pactl list sinks

Input Issues

Keyboard Layout Problems

Incorrect keyboard layouts can be fixed by checking hyprctl and your keyboard configuration.

# Check current layout
hyprctl devices

# Edit keyboard config (adjust path if needed)
nano ~/.config/hypr/conf/keyboard.conf

# Reload Hyprland config to apply changes
hyprctl reload

Keybindings Not Working

If your keybindings aren’t responding, verify your configuration.

# Check keybinding configuration (adjust path if needed)
cat ~/.config/hypr/conf/keybindings/default.conf

# Test individual binds (example: launch kitty)
hyprctl dispatch exec kitty

Network Issues

NetworkManager Not Working

Network connectivity issues are often related to NetworkManager.

# Check NetworkManager service status
systemctl status NetworkManager

# Enable and start NetworkManager (if not running)
sudo systemctl enable --now NetworkManager

# Start nm-applet (for graphical network management)
nm-applet &

System Integration

Auto-login Not Working

If auto-login isn’t functioning, check your .zprofile and TTY setup.

# Check .zprofile content
cat ~/.zprofile

# Verify current TTY
echo $XDG_VTNR

Clipboard Issues

Clipboard problems can often be resolved by restarting cliphist.

# Restart cliphist
pkill wl-paste
wl-paste --watch cliphist store &

# Check clipboard history
cliphist list

Getting Help

If the above solutions don’t resolve your issue, gather relevant information before seeking further assistance.

Log Collection

Provide logs to help diagnose the problem.

# Hyprland logs (last 50 lines)
tail -n 50 ~/.cache/hyprland/hyprland.log

# User-specific Hyprland logs (real-time)
journalctl --user -u hyprland -f

# Waybar logs (real-time)
journalctl --user -u waybar -f

System Information

Share your system details.

# Hardware info
fastfetch

# Hyprland version
hyprctl version

# Key package versions
pacman -Q | grep -E "(hyprland|waybar|rofi)"

Reset Configuration

As a last resort, you can reset your HyprL configuration. This will remove your custom settings.

# Backup current config (important!)
cp -r ~/.config ~/.config-backup-$(date +%s)

# Remove HyprL related configs
rm -rf ~/.config/hypr ~/.config/waybar ~/.config/rofi

# Re-run the installation script
bash <(curl -sL https://raw.githubusercontent.com/Manpreet113/hyprL/master/main/setup.sh)

📧 Still Need Help?

If you’re still facing issues after trying these steps:

  1. Check GitHub Issues: Look for similar problems and solutions on the HyprL GitHub Issues page.
  2. Create a new issue: If you can’t find a solution, create a new issue on GitHub. Include:
    • Your system info (fastfetch output).
    • A detailed description of the problem.
    • Steps to reproduce the issue.
    • Any relevant log files.
  3. Join the community: Join our Discord server for further assistance or if I forgot some issues.