hyprland-debug

Diagnose Hyprland/Wayland issues by parsing logs and validating state.

3|Updated Jul 17, 2024

Search Tags:#logging #diagnose #wayland #nixos #systemd #hyprland #hyprctl

Ready to run

npx skills add https://github.com/Castrozan/.dotfiles --skill hyprland-debug

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: hyprland-debug
Source: https://github.com/Castrozan/.dotfiles/tree/main/agents/skills/hyprland-debug
Command: npx skills add https://github.com/Castrozan/.dotfiles --skill hyprland-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diagnosing Hyprland/Wayland issues.

Core Features & Use Cases

Centralized log analysis: aggregates Hyprland logs from /run/user/$(id -u)/hypr/*/hyprland.log and surfaces common failure signals.
Deterministic checks: validates HYPRLAND_INSTANCE_SIGNATURE and ensures state consistency to avoid stale sessions.
Use Case: When theme switching fails, windows disappear, services crash, or displays malfunction, it identifies root causes and suggests fixes.

Quick Start

Use the hyprland-debug skill to diagnose current Hyprland issues and surface actionable fixes.

Frequently Asked Questions about hyprland-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose Hyprland issues when windows disappear or displays malfunction?▼

Diagnosing Hyprland issues involves aggregating logs from /run/user/$(id -u)/hypr/*/hyprland.log and verifying state via HYPRLAND_INSTANCE_SIGNATURE to identify root causes for disappearing windows or malfunctioning displays.

Why does my Wayland theme switching fail and how can I find the root cause?▼

Wayland theme switching fails due to state inconsistencies or crashing user services. You can find the root cause by parsing Hyprland logs and verifying your HYPRLAND_INSTANCE_SIGNATURE to avoid stale sessions.

Can I use systemd to debug Hyprland services when they crash?▼

Yes, you can debug Hyprland services by parsing systemd user service logs alongside Hyprland's internal logs. This process verifies the active HYPRLAND_INSTANCE_SIGNATURE and checks for failure signals to surface actionable fixes.

Does NixOS require special steps to troubleshoot Hyprland log errors?▼

Troubleshooting Hyprland log errors on NixOS requires accessing logs located at /run/user/$(id -u)/hypr/*/hyprland.log. You must validate the HYPRLAND_INSTANCE_SIGNATURE to ensure state consistency before applying fixes.

What's the best way to identify stale Hyprland sessions causing display malfunctions?▼

The best way to identify stale Hyprland sessions causing display malfunctions is to run deterministic checks that validate the HYPRLAND_INSTANCE_SIGNATURE against your current user services and parse the active instance logs.

What should I do if hyprctl reports state inconsistencies during a Wayland session?▼

If hyprctl reports state inconsistencies during a Wayland session, you should aggregate logs from /run/user/$(id -u)/hypr/*/hyprland.log to surface failure signals and verify your HYPRLAND_INSTANCE_SIGNATURE.