Hyprland — Wayland Compositor

Hyprland compositor patterns — config debugging with hyprctl configerrors, bind conflict detection, deprecated options for 0.53+, IPC queries, and the tmux socket fix.

Config Debugging

The Two Error Systems

Hyprland has two separate error sources — mixing them up wastes hours.

System Command What it shows

System	Command	What it shows
Config parser	`hyprctl configerrors`	Syntax errors with file + line number. This is what you want 95% of the time.
Runtime log	`hyprland.log`	GPU page-flips, DRM commits, renderer issues. Noisy. Not for config errors.

Config parser

hyprctl configerrors

Syntax errors with file + line number. This is what you want 95% of the time.

Runtime log

hyprland.log

GPU page-flips, DRM commits, renderer issues. Noisy. Not for config errors.

Core Commands

THE command — shows config errors with file and line number

hyprctl configerrors
# Output (when errors exist):
# /home/evan/.config/hypr/hyprland.conf:136 - invalid value "true" for variable "new_optimizations"

Reload config without restarting compositor

hyprctl reload

Combo: reload then check

hyprctl reload && hyprctl configerrors

Check runtime value of any config option

hyprctl getoption decoration:dim_inactive
hyprctl getoption cursor:no_hardware_cursors

Inspecting Binds

List all active binds as JSON

# Flag BEFORE subcommand — hyprctl -j binds, NOT hyprctl binds -j
hyprctl -j binds | jq -r '.[] | "\(.modmask) \(.key) → \(.dispatcher) \(.arg)"'

Find duplicate/conflicting binds

hyprctl -j binds | jq -r '.[] | "\(.modmask) \(.key) → \(.dispatcher) \(.arg)"' | sort | uniq -d -w 20
# Duplicate binds = later one silently shadows earlier one
# No error, no warning — the first bind just stops working

Runtime Log (GPU/DRM)

Log path

/run/user/$(id -u)/hypr/$(ls /run/user/$(id -u)/hypr/)/hyprland.log

Filter out GPU noise

grep -n -iE 'err|fail|invalid' /run/user/$(id -u)/hypr/$(ls /run/user/$(id -u)/hypr/)/hyprland.log | \
    grep -vi 'gesture\|libinput\|GL_\|EGL\|drm'

Hyprland IPC

General system queries

hyprctl -j version | jq -r '.tag'     # current version
hyprctl -j clients                      # list all windows
hyprctl -j monitors                     # list all displays
hyprctl systeminfo                      # full system/config dump

Config Patterns and Gotchas

Bind Conflicts — Silent Shadowing

Later binds override earlier ones with no warning. The first bind silently stops working.

Table 1. Conflicts found (2026-04-10)
Original bind	Was shadowing	Remapped to
SUPER+J → DJ toggle	movefocus, d (vim nav down)	SUPER+SHIFT+A
SUPER+SHIFT+S → shader cycle	scratchpad toggle	SUPER+SHIFT+/
SUPER+SHIFT+G → animated wallpaper	moveintogroup	SUPER+ALT+SHIFT+G

Detection: find duplicate binds

hyprctl -j binds | jq -r '.[] | "\(.modmask) \(.key) → \(.dispatcher) \(.arg)"' | sort | uniq -d -w 20

Deprecated Options (Hyprland 0.53+)

Removed Replacement

Removed	Replacement
`new_optimizations = true` in blur	Always on — remove the line entirely
`allow_tearing = false` in general	Moved to `render { allow_tearing = false }`
`WLR_NO_HARDWARE_CURSORS=1` in env	`cursor { no_hardware_cursors = true }`
`gestures {}` block	Removed — workspace swipe is native, configure in `input {}`

new_optimizations = true in blur

Always on — remove the line entirely

allow_tearing = false in general

Moved to render { allow_tearing = false }

WLR_NO_HARDWARE_CURSORS=1 in env

cursor { no_hardware_cursors = true }

gestures {} block

Removed — workspace swipe is native, configure in input {}

tmux + Hyprland Socket Fix

tmux inherits environment at server start — HYPRLAND_INSTANCE_SIGNATURE is missing in new sessions.

Fix for current session

export HYPRLAND_INSTANCE_SIGNATURE=$(ls /run/user/$(id -u)/hypr/ | head -1)

Permanent fix in .tmux.conf

set-option -g update-environment "HYPRLAND_INSTANCE_SIGNATURE WAYLAND_DISPLAY DISPLAY"

Optimization Patterns

Brightness notification — raw value vs percentage

# WRONG — shows raw value like 19200%
brightnessctl get

# CORRECT — machine-readable output, extract percentage
brightnessctl -m | awk -F, '{print $4}'
# Output: 75%

hyprlock uptime — sed chain vs awk

# BEFORE — 5-pipe sed chain
uptime | sed 's/.*up //' | sed 's/, .*//' | sed 's/ days/d/' | sed 's/ hours/h/' | sed 's/ min/m/'

# AFTER — single awk with gsub
uptime | awk '{gsub(/.*up |, .*/, ""); gsub(/ days?/, "d"); gsub(/ hours?/, "h"); gsub(/ min/, "m"); print}'

hyprctl flag position matters

# WRONG — flag after subcommand
hyprctl devices -j

# CORRECT — flag before subcommand
hyprctl -j devices