Troubleshooting

No display

GPU driver issues

No sound

PipeWire setup

Theme broken

Theme system

Slow/laggy

Performance

Display Issues

Hyprland won't start

Symptoms: Black screen, crashes on login, “failed to find GPU” errors.

Solutions:

1. Check GPU driver is loaded:

dmesg | grep -i drm
kldstat | grep drm

2. Load the correct DRM module:

# Intel
sudo kldload i915kms

# AMD
sudo kldload amdgpu

# Add to /etc/rc.conf for persistence
kld_list="i915kms"

3. Verify Wayland socket:

ls -la /var/run/xdg/$USER/

4. Try starting manually with debug output:

Hyprland 2>&1 | tee ~/hyprland.log

Screen flickering

Solutions:

1. Disable VRR (Variable Refresh Rate):

# ~/.config/hypr/hyprland.conf
misc {
    vrr = 0
}

2. Force a specific refresh rate:

# ~/.config/hypr/conf/monitors.conf
monitor=,1920x1080@60,auto,1

HiDPI scaling issues

Edit ~/.config/hypr/conf/monitors.conf:

# Scale factor (1.5 = 150%)
monitor=eDP-1,preferred,auto,1.5

# Or set Xwayland scale
xwayland {
    force_zero_scaling = true
}

Set environment variables in ~/.config/hypr/hyprland.conf:

env = GDK_SCALE,2
env = QT_SCALE_FACTOR,2

Theme Issues

Theme not applying

Solutions:

1. Check theme exists:

ls ~/.config/omfreebdy/themes/
theme-set --list

2. Apply theme manually with verbose output:

bash -x ~/.local/bin/theme-set tokyo-night 2>&1

3. Check for syntax errors in colors.toml:

cat ~/.config/omfreebdy/themes/tokyo-night/colors.toml

4. Verify jq is installed (required for VSCode theming):

pkg info jq || sudo pkg install jq

Neovim theme not updating

Solutions:

1. Check SIGUSR1 handler is registered:

nvim --headless -c "autocmd" -c "q" 2>&1 | grep Signal

2. Manually reload in Neovim:

:source ~/.config/nvim/init.lua
:colorscheme tokyonight

3. Restart Neovim after theme change.

GTK apps using wrong theme

Solutions:

1. Check gsettings:

gsettings get org.gnome.desktop.interface color-scheme
gsettings get org.gnome.desktop.interface gtk-theme

2. Set manually:

gsettings set org.gnome.desktop.interface color-scheme "prefer-dark"
gsettings set org.gnome.desktop.interface gtk-theme "Adwaita-dark"

3. Restart affected apps.

Audio Issues

No sound

Solutions:

1. Check PipeWire is running:

pw-cli info
pgrep pipewire

2. Start PipeWire:

pipewire &
wireplumber &

3. Check audio sinks:

pactl list sinks short
wpctl status

4. Set default sink:

wpctl set-default <sink-id>

Volume keys not working

Solutions:

1. Check keybindings in ~/.config/hypr/conf/bindings.conf

2. Verify scripts are executable:

chmod +x ~/.local/bin/volume

3. Test manually:

~/.local/bin/volume up
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+

Keyboard Issues

Media keys not detected

Use wev to check key codes:

pkg install wev
wev
# Press key and note the key name

Add binding:

# ~/.config/hypr/conf/bindings.conf
bind = , XF86AudioRaiseVolume, exec, volume up

Wrong keyboard layout

Edit ~/.config/hypr/hyprland.conf:

input {
    kb_layout = us
    kb_variant =
    kb_options = ctrl:nocaps
}

For multiple layouts:

input {
    kb_layout = us,de
    kb_options = grp:alt_shift_toggle
}

Performance Issues

High CPU usage

Solutions:

1. Disable blur effects:

# ~/.config/hypr/conf/looknfeel.conf
decoration {
    blur {
        enabled = false
    }
}

2. Reduce animations:

animations {
    enabled = false
}

3. Check for runaway processes:

top -o cpu

Slow application launches

Solutions:

1. Rebuild font cache:

fc-cache -fv

2. Check D-Bus:

dbus-daemon --session &

Network Issues

WiFi not connecting

Solutions:

1. Check interface:

ifconfig wlan0

2. Scan networks:

wpa_cli scan
wpa_cli scan_results

3. Use wifi-manager:

wifi-manager select

Getting Debug Info

Collect system information for bug reports:

# System info
uname -a
freebsd-version

# GPU info
pciconf -lv | grep -A4 vga

# Hyprland version
hyprctl version

# Current config
cat ~/.config/hypr/hyprland.conf

# Recent logs
cat ~/.local/share/hyprland/hyprland.log | tail -100

Resetting to Defaults

Warning: This will overwrite your current configuration. Make sure to backup first.

# Backup current config
cp -r ~/.config/hypr ~/.config/hypr.bak

# Reinstall default configs
cd ~/.omfreebdy
mise run apply

# Or reset specific components
cp ~/.omfreebdy/config/hypr/* ~/.config/hypr/

Reporting Issues

When reporting issues, include:

1. FreeBSD version: freebsd-version
2. GPU model: pciconf -lv | grep -A4 vga
3. Hyprland version: hyprctl version
4. Steps to reproduce
5. Expected vs actual behavior
6. Relevant log output

File issues at: https://gitlab.daringbit.com/josh/omfreebdy/-/issues